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

# Errors and retries

> Handle Qoory error envelopes, status codes, retries, and request tracing.

Errors use the same envelope shape as successful responses:

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request could not be validated."
  },
  "meta": {
    "request_id": "req_example_12345"
  }
}
```

## Error classes

| Status | Representative codes                                                        | Action                                                                                          |
| -----: | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|  `401` | `MISSING_API_KEY`, `INVALID_API_KEY`, `DISABLED_API_KEY`, `REVOKED_API_KEY` | Fix or replace the credential; do not retry unchanged.                                          |
|  `402` | `INSUFFICIENT_CREDITS`                                                      | Wait for the free reset or add shared credits.                                                  |
|  `403` | `FORBIDDEN`, `USER_SUSPENDED`, `FEATURE_DISABLED`                           | Check scopes and account access; do not retry unchanged.                                        |
|  `404` | `NOT_FOUND`                                                                 | Re-resolve the identity or stop. Gated operations can also return a neutral not-found response. |
|  `422` | `INVALID_REQUEST`                                                           | Correct fields, filters, or identifiers.                                                        |
|  `429` | `RATE_LIMITED`                                                              | Wait for `Retry-After` or the rate-limit reset time.                                            |
|  `500` | `INTERNAL_ERROR`, `CONFIGURATION_ERROR`, `DATA_UNAVAILABLE`                 | Retry only transient failures with bounded backoff.                                             |

## Retry policy

Retry idempotent `GET` requests and a search `POST` only when the failure is
transient. Use exponential backoff with jitter, honor `Retry-After`, cap the
number of attempts, and keep an overall deadline. Do not retry `401`, `402`,
`403`, `404`, or `422` without changing the underlying condition.

Record `meta.request_id` or `x-qoory-request-id` with the operation, timestamp,
and status. Never include the bearer secret in a support report.