# Handle errors

The shape of error responses, and which errors you can retry as they are.

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](./api-docs-en-idempotency.md#conflict); 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](./api-docs-en-api-errors.md).

## Details

- `unsupported_capability`: `error.details` lists the capabilities that cannot be met together and the request parameters involved; adjust those parameters.
- `insufficient_balance`: `error.details` gives 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](./api-docs-en-api-statuses.md#task-error). Failed tasks are settled at no charge.

## Next steps

- [Error codes](./api-docs-en-api-errors.md): Every error.code with its meaning, status and endpoints.
- [Idempotency and retries](./api-docs-en-idempotency.md): Retry with the same Idempotency-Key to get exactly one task and one charge.