Errors and recovery
Diagnose a failed request using its HTTP status, error code and request ID. Some successful responses contain files; errors use a JSON envelope.
Read the error envelope
Failures use a JSON error envelope even when the successful response is binary. Check status before treating the body as an image. Request IDs are illustrative below.
{
"success": false,
"error": {
"code": "TRANSFORM_INVALID",
"message": "Transformation parameters are invalid or unsupported.",
"details": {}
},
"meta": {
"requestId": "example-request-id"
}
}error.details is currently an empty object in the sanitized response. Do not depend on stack traces, internal database errors or arbitrary validation text. Record the request ID and operation for support without recording credentials or private image content.
Common media error codes
| Status | Code | Action |
|---|---|---|
| 400 | BAD_REQUEST, IMAGE_INVALID, TRANSFORM_INVALID, TOOL_INVALID, PDF_INVALID, PDF_ENCRYPTED, CAPTCHA_FAILED, CONTACT_INVALID | Correct malformed body, unsupported options, byte mismatch or invalid image. |
| 400 | REMOTE_URL_INVALID, REMOTE_URL_BLOCKED | Use an allowed source; do not bypass destination safeguards. |
| 401 | API_KEY_INVALID, API_KEY_REVOKED, AUTH_TOKEN_INVALID, AUTH_TOKEN_EXPIRED | Check one valid credential and the correct realm. |
| 403 | AUTH_EMAIL_UNVERIFIED, SUBSCRIPTION_INACTIVE, PLAN_LIMIT_EXCEEDED, FEATURE_DISABLED | Resolve verification, entitlement, capacity allowance or feature availability. |
| 404 | PROJECT_NOT_FOUND, IMAGE_NOT_FOUND, TRANSFORM_NOT_FOUND | Check IDs, ownership, active state and expiry. Scope failures may also return 404. |
| 409 | IMAGE_CONFLICT, TRANSFORM_CONFLICT, USAGE_CONFLICT | Inspect existing work; retry only when the conflicting operation settles. |
| 413 | IMAGE_TOO_LARGE, IMAGE_PIXEL_LIMIT_EXCEEDED, IMAGE_FRAME_LIMIT_EXCEEDED, PAYLOAD_TOO_LARGE, PDF_TOO_LARGE, PDF_PAGE_LIMIT_EXCEEDED | Reduce bytes, decoded pixels, frames or output cap as appropriate. |
| 415 | IMAGE_FORMAT_NOT_SUPPORTED, UNSUPPORTED_MEDIA_TYPE | Use a supported validated file or request content type. |
| 429 | RATE_LIMIT_EXCEEDED | Reduce request frequency; retry with bounded backoff and jitter. |
| 502 | REMOTE_FETCH_FAILED, TOOL_FAILED | Check source availability; do not loop indefinitely. |
| 503 | IMAGE_BUSY, TOOL_BUSY, PLAN_UNAVAILABLE, MAINTENANCE, SERVICE_UNAVAILABLE | Wait for capacity or service recovery; cap retries. |
| 500 | INTERNAL_SERVER_ERROR, STORAGE_INVALID_KEY | Keep the request ID and contact support if it persists. |
Retry deliberately
Do not retry invalid input, denied access or exhausted account allowances unchanged. For temporary 429/503 or in-progress 409 responses, use bounded exponential backoff with jitter. Honor Retry-After when present, but do not assume every limiter emits it.
Upload POST has no documented idempotency key: a lost response can leave an uploaded original. Check your media list before repeating it. Cache reuse is not a general idempotency guarantee; EPHEMERAL always recomputes and remote input is fetched again.
Client aborts and timeouts do not guarantee cancellation or a refund. Once transfer bandwidth is admitted, disconnecting does not refund it. If a stream fails after headers have been sent, you may receive a truncated body rather than a fresh JSON envelope.
Get help
Use account support with the request ID, time, method and error code. Do not include tokens, API keys or unnecessary private content.
Documentation reviewed 2026-10-03 against development backend e298ec7. Verify your deployment’s API origin and limits before integrating.