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

# Errors

> Handle API v1 error responses and correlation IDs.

API v1 returns errors as JSON under the `error` property:

```json theme={null}
{
  "error": {
    "code": "api_unauthorized",
    "message": "Authentication required."
  }
}
```

`code` is the machine-readable value. `message` is a short description. Some
errors also include `details` and `correlation_id`.

## Status codes

Use the HTTP status and `error.code` together:

| Status | Meaning |
| - | - |
| `400` | The request could not be parsed. |
| `401` | The request has no accepted API credential. |
| `403` | The credential lacks the required scope or account access. |
| `404` | The requested resource was not found. |
| `409` | The requested change conflicts with the current resource state. |
| `413` | The request body exceeds a request limit. |
| `415` | A request body does not use an accepted JSON content type. |
| `422` | The request does not match the endpoint contract. |
| `429` | A rate limit denied the request. |
| `500` | The API could not produce a valid response. |
| `503` | A required service was unavailable. |

Each endpoint reference lists the exact error codes it can return.

## Correlation IDs

Every API v1 response includes `X-Correlation-ID`. Error bodies can also
include the same value as `error.correlation_id`.

Record the correlation ID with the status code and `error.code` when you
investigate a failed request. Do not log the Bearer credential or response
fields that may contain personal data.

## Retry decisions

* For `429`, wait for the number of seconds in `Retry-After` before retrying.
* For `503`, do not treat the response as a quota reset. A limiter outage uses
  `rate_limiter_unavailable` and does not include `Retry-After`.
* For `401` or `403`, correct the credential, scope, or account access instead
  of retrying the same request.
* For `422`, correct the request using the endpoint reference.

Read [Rate limits](/guides/rate-limits) for the complete `429` behavior.