Handle errors
The shape of error responses, and which errors you can retry as they are.
On this page
The HTTP status says how a request ended, and an error response carries a machine-readable code. Write your handling against the code, never against the message text.
Error shape
An error response has an error object and a trace_id:
| Field | Meaning |
|---|---|
error.code | Machine-readable code; handle errors by it. |
error.message | Readable explanation that may change; do not branch on it. |
error.details | Optional structured details, such as the reservation needed when the balance is low. |
trace_id | Trace ID for investigation; include it when you contact us. |
Can you retry?
| Case | What to do |
|---|---|
400, 401, 403, 404 | The request itself is wrong and fails again as it is. Fix it by the code, then send it. |
409 | Mostly an idempotency conflict, see Idempotency and retries; for asset_not_ready, retry with the same key once the asset is active. |
429 | A rate, balance or allowance limit. With Retry-After, wait that many seconds and retry with the same key; top up first when the balance is low. |
500, 503 | The outcome is unknown. Retry the same body with the same Idempotency-Key; nothing is created or charged twice. |
| Timeout or dropped connection | As above: retry as it is with the same key. |
The meaning of every code, what to do and whether it is charged are on Error codes.
Details
unsupported_capability:error.detailslists the capabilities that cannot be met together and the request parameters involved; adjust those parameters.insufficient_balance:error.detailsgives the reservation the request needs and its price version.
Failed tasks
A request the API accepted can still fail in the background. A failed task has status failed and a reason in error.code, such as input_fetch_failed or generation_failed; every value is on Statuses and reasons. Failed tasks are settled at no charge.