# Errors and retries

## Error responses

Task API failures return an HTTP error status and a JSON object with string `code` and `message` fields. Preserve `X-Request-ID` when contacting support.

| HTTP | Code | Retry? | Action |
| --- | --- | --- | --- |
| 400 | `invalid_params` | No | Correct the request against the model's inputs. |
| 401 | `unauthorized` | No | Check or replace the API key. |
| 402 | `insufficient_balance` | No | Check the account balance and recharge. |
| 403 | `access_denied` | No | Check account access and model entitlements. |
| 404 | `not_found` | No | Check the task ID and account ownership. |
| 409 | `conflict` | No | Check the idempotency payload or model revision. |
| 429 | `concurrency_limit` / `rate_limit` | Yes, after `Retry-After` | Back off and wait for available capacity. |
| 500 | `internal_error` | Yes, with the same idempotency key | Preserve diagnostics and retry. |
| 503 | `service_unavailable` | Yes, after backoff | Back off and check service availability. |

Retrying `recordInfo` is always safe. For `createTask`, follow the idempotency rules below before retrying anything.

See [rate limits and concurrency](/docs/rate-limits) for the `Retry-After` header and backoff guidance.

## Recover a lost create response

Keep the idempotency key and request body from the first attempt. Retry the same logical submission using both. Matching replays return the existing task. A changed payload with the same key is rejected. When upstream acceptance is still pending reconciliation, wait for the original task.

If you did not send an `Idempotency-Key`, do not retry a `createTask` whose response you never received. You cannot tell whether the first attempt created a task, and a blind retry can charge twice. Record every returned task ID and treat an ambiguous submission as "unknown" until you can confirm it.

## Generation failures

A successful `recordInfo` HTTP response can contain `status: fail`. Inspect its nested `error` object. `waiting` and `generating` mean the task is still pending. Confirmed generation failures refund the reservation.

Some failure codes are upstream conditions rather than your mistake:

| Code | Meaning |
| --- | --- |
| `generation_failed` | The model could not produce an output for this input. |
| `no_provider` | No channel was available for this model at submit time. Retry later. |
| `provider_out_of_credits` | The platform could not reach an upstream channel. Not your balance. |
| `content_policy` | The prompt or reference media was rejected. Adjust the input. |

`provider_out_of_credits` and `no_provider` are **not** caused by your account balance. Do not top up in response to them.

Use [service status](/status) and the [model documentation](/docs/models) to check current availability and supported parameters.