Errors & retries
Handle errors, retries and shared limits without duplicate charges.
Error shape
{
"error": {
"code": "invalid_parameters",
"message": "Unsupported resolution."
}
}Errors use application/json and the HTTP status. Check error.code; do not depend on the message text.
Idempotency
Every video/image create request requires an Idempotency-Key of 16–128 letters, digits, underscores or hyphens. Persist it with the intended business operation. Same key and body replays the original generation without a second charge; different parameters return 409 idempotency_conflict. Keep the same API key for retries and polling.
Common responses
| HTTP | Code | Action |
|---|---|---|
| 401 | invalid_api_key | Check or replace the key. |
| 403 | api_key_upgrade_required | Create a new key. |
| 403 | server_side_only | Call from your server. |
| 403 | paid_account_required | Use an active paid plan or purchased credits. |
| 404 | generation_not_found | Check the ID and original API key. |
| 409 | idempotency_conflict | Restore the original request body. |
| 409 | cost_limit_exceeded | Review the quote and cost cap. |
| 413 | request_too_large | Reduce the request size. |
| 422 | invalid_parameters | Correct fields against the model catalog. |
| 429 | rate_limit_exceeded / concurrency_limit_exceeded / daily_spend_limit_exceeded | Respect Retry-After and account limits. |
| 503 | api_unavailable / service_unavailable | Back off and retry the same request. |
Safe retries
For network failures, 429 and 503, use backoff and keep the exact same request identity. A 409 generation_rejected explicitly means rejection before submission: correct the issue before a new request. Never turn an uncertain timeout into a new generation automatically. The edge firewall can return a non-JSON 403 after 120 requests/IP/minute; wait for its window to reset.