Find the symptom, then the fix. Error codes are explained on the errors page. When you contact support, include the x-request-id of the failing response.
| Symptom | Likely cause | Fix |
|---|---|---|
| Creating an SVG upload answers 400 unsupported_content_type or 413 file_too_large | SVG uploads are not enabled on this deployment (400), or the SVG is above 2 MB (413). | Upload the image as PNG or WebP, or reduce the SVG below 2 MB. |
| The PUT to put_url answers 403 from the storage host | The request headers differ from the signed ones, or the URL expired (15 minutes). | Send exactly the returned headers and the exact size_bytes; create a new session if it expired. |
| The browser PUT fails with a CORS or network error | A network or extension blocks the storage host. | Leave mode unset so the SDK falls back to the upload proxy, or pass mode: "proxy". |
| Multipart fails with etag_missing | The browser cannot read the ETag response header. | Use the SDK defaults; report it to support if it persists. |
| The session stays created | The bytes never arrived. | Check the PUT response, then call complete; the session expires after 15 minutes. |
| The session is failed | Processing refused the file; see error_code. | See the processing errors; animated images and HEIC are refused, as are JPEG and PNG images over 128 megapixels and other formats over 50 megapixels (AVIF and some WebP less). SVGs are refused with embedded bitmap images or a DOCTYPE, or when too complex to render safely. image_too_large can also mean the image is too costly to process, for example a palette PNG that becomes too large when re-encoded. |
| onUploadComplete ran twice | The browser repeated the complete call. | Make the hook idempotent, keyed on upload_id. |
| Symptom | Likely cause | Fix |
|---|---|---|
401 unauthorized | Missing, mistyped, revoked or rotated key. | Send X-Api-Key or Authorization: Bearer with the current key; GET /v1/key shows what a key can do. |
403 forbidden | The key lacks a scope. | Create a key with the scope (see authentication) or one without scopes. |
403 browser_session_required | The route is dashboard-only. | Change keys, settings and billing in the dashboard. |
404 on a project that exists | The key belongs to another project. | Use the key of the project in the path. |
429 rate_limited | Too many failed authentications or writes. | Fix the credential, then retry after Retry-After. |
| Symptom | Likely cause | Fix |
|---|---|---|
404 for a URL with ?v= or another query string | Unsigned delivery URLs may not carry a query string. | Drop it; a re-upload updates the URL on its own. |
404 for a transform URL | The chain does not parse, uses an unknown preset, repeats an operation, or /f/ is missing. | Check it against the grammar. |
403 signature_required | The project is protected. | Serve signed URLs minted by your server. |
403 signature_expired | The signed URL is past exp. | Mint a new one; pick an expiry that covers the page lifetime. |
403 unknown_kid | The signing key was rotated more than 24 hours ago. | Mint the URL again. |
403 file_blocked | Moderation blocked the file. | Show a fallback; the file.unblocked webhook tells you when it is served again. |
403 quota_exceeded | The organization has no credits. | Add credits in billing (see usage and billing). |
| An old version after a re-upload | Your browser cache (up to five minutes), or a delivery server's file cache (up to 30 seconds). | Wait or reload; the CDN purge after a re-upload is queued, not instant. |
| A deleted or blocked file still loads | Delivery servers cache file lookups for up to 30 seconds, and the CDN purge is queued. | Wait a minute; browsers may keep their copy for up to five minutes. |
signature_mismatch: verify the raw body; a body parsed and serialized again no longer matches.timestamp_out_of_tolerance: synchronize your server clock.callback_url that resolves to a public https address.