> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ekly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error has the same shape and a small, stable set of codes.

Any response outside the 2xx range looks like this:

```json theme={null}
{
  "error": {
    "code": "payment_required",
    "message": "Insufficient credits for this generation.",
    "trace_id": "c3746d5302dc4be6b2e8fa99fa762a8c",
    "details": []
  }
}
```

`details` appears only on validation errors and lists each offending field. Quote `trace_id` when
you write to support; it finds the exact request.

## Codes

| HTTP | `code` | What to do |
| - | - | - |
| 401 | `unauthenticated`, `invalid_api_key` | The key is missing, revoked, expired or wrong. Create a new one in Settings → Team. |
| 402 | `payment_required` | Not enough credits. Top up, then retry. |
| 403 | `forbidden`, `api_key_scope` | Keys only call `/v1`; or your plan cannot use this model. |
| 404 | `not_found` | Wrong id, or the API is not enabled for this environment. |
| 409 | `conflict` | An `Idempotency-Key` was reused with a different body. Use a new key. |
| 422 | `validation_error` | A field is missing, unknown or out of range. See `details`. |
| 429 | `rate_limited` | Wait the number of seconds in `Retry-After`, then retry. |
| 5xx | `internal_error` | Retry with backoff; include `trace_id` if it persists. |

## Generation failures are not HTTP errors

A generation that was accepted but did not finish is a `200` with `"status": "failed"` and an
`error` object on the generation itself. Its `code` is one of `rate_limited`, `timeout`, `safety`,
`invalid_voice`, `invalid_request`, `billing_or_access`, `provider_auth`, `provider_unavailable`,
`provider_error`. `safety` and `invalid_request` need a different prompt or input; the others are
worth one retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.