Skip to main content

Troubleshooting Production Issues and System Status

Use this guide when a live Imgwire integration is failing or degraded. It helps you separate application issues from Imgwire API, upload, CDN delivery, custom domain, quota, and account problems.

Identify which surface is failing​

Start by finding the failing surface:

Failing surfaceWhat to check first
DashboardAccount access, organization selection, billing state
Resource APIServer API Key, X-Environment-Id, endpoint, error body
Browser uploadsClient Key settings, CORS origins, signed upload token endpoint
Presigned upload URLFile upload PUT, content type, network timeout
CDN deliveryImage ID, image READY status, transformation URL, default CDN hostname
Custom domain deliveryDefault CDN URL, DNS records, custom domain status, certificate status
AI agent or MCP toolsAuthorized Connection, Environment binding, OAuth reauthorization

Capture the exact URL, method, response status, and error body before changing code.

Compare default CDN and custom domain delivery​

If a custom domain image fails, test the same image on the default Imgwire CDN hostname.

If the default CDN URL works but the custom domain fails:

  • Check Custom Domains.
  • Confirm status is CONNECTED.
  • Confirm certificate_status is ACTIVE.
  • Run POST /api/v1/custom_domain/test_connection.
  • Keep the default CDN URL as a fallback while DNS or certificate validation completes.

If both URLs fail, inspect the image record and transformation parameters.

Check API errors​

Imgwire domain errors include detail and error_type:

{
  "detail": "Resource not found.",
  "error_type": "ResourceNotFoundError"
}

Common production error types:

Error typeMeaning to investigate
InvalidTokenErrorKey, upload token, or bearer credential is invalid
ResourceNotAuthorizedErrorUser, key, or connection cannot access that resource
OperationNotAllowedErrorRole or operation permission is insufficient
PaymentRequiredErrorSubscription, plan, or quota condition blocks the operation
InvalidStateErrorRequest data or resource state is invalid
ResourceNotFoundErrorEnvironment, image, domain, or other resource was not found
RateLimitExceededErrorAPI request rate exceeded the allowed rate

Use the response body instead of relying only on the HTTP status code.

Inspect metrics​

Use the dashboard Metrics page or the Metrics Resource API to compare current production behavior to previous periods.

Useful signals:

  • Uploads: are new uploads reaching READY?
  • Requests: did CDN request volume drop or spike?
  • Transfer bytes: did image delivery volume change?
  • Transformations: are many new variants being computed?
  • Cache hit ratio: did the app start producing many unique transformation URLs?
  • Storage bytes: did the organization approach storage capacity?

Metrics are rolled up asynchronously, so very recent events may not be visible immediately.

Mitigate safely​

When production is affected:

  • Do not expose a Server API Key in frontend code as a quick fix.
  • Keep default CDN URLs available until a custom domain is connected and certificate-active.
  • If uploads are failing, preserve the original files or retry queue so users do not lose work.
  • If transformations are slow or expensive, reduce unique transformation URL generation and use stable presets or widths.
  • If quota or billing is blocking uploads, review the Billing page before deleting data or changing plan settings.

When to report the issue​

Report the issue when:

  • The same request fails across multiple environments or machines.
  • Default CDN delivery fails for a READY image.
  • The Resource API returns repeated 5xx or ExternalServiceError responses.
  • Custom domain validation appears correct but does not connect after DNS propagation.
  • Billing, quota, or account state appears inconsistent with dashboard data.

See Report an Issue for what to include.

Last updated at: May 8, 2026