Get started
Error codes
Every error response carries a stable code, a human-readable message, and the request_id for support lookups. Branch on the code — never on the message string.
Catalog
All public codes
| Code | HTTP | Meaning |
|---|---|---|
| authentication_failed | 401 | Missing or invalid bearer token. |
| account_disabled | 403 | Key or customer is paused. |
| origin_not_allowed | 403 | Key has an allowed-origin list and the request Origin didn't match. |
| ip_not_allowed | 403 | Key has an allowed-IP list and the request IP didn't match. |
| invalid_request | 400 | Body failed validation. |
| invalid_product | 400 | Unknown product id. |
| source_image_required | 400 | This model needs a source image. Provide source_image_url (or start_image_url for video). |
| invalid_image | 400 | An uploaded image could not be decoded. |
| image_too_large | 400 | An uploaded image exceeded the size cap. |
| insufficient_balance | 402 | Not enough credits. Top up to continue. |
| product_paused | 409 | Product temporarily unavailable. |
| invalid_state | 409 | The job isn't in a state that supports this action (e.g. retrying a non-failed job). |
| idempotency_conflict | 409 | Idempotency-Key reused with a different request body. |
| invalid_pack | 400 | Unknown top-up pack. |
| rate_limited | 429 | Too many requests. Slow down and honor Retry-After. |
| queue_full | 429 | Too many unfinished jobs queued under this key. |
| rate_limiter_unavailable | 503 | Rate limiter is temporarily unreachable; requests are rejected fail-closed. Retry shortly. |
| service_unavailable | 502 / 503 | Backend is temporarily unavailable. Retry with backoff. |
| not_found | 404 | Resource does not exist or isn't owned by your key. |
| generation_failed | async | Generation could not be produced. Credits are refunded automatically. |
Retry policy
Safe retries
Retry 429 and 503 with exponential backoff and jitter. Honor the Retry-After header when present. Always include the same Idempotency-Key on retries so the call cannot double-charge.