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

# Errors

> How the Neo API reports errors — the error envelope, status codes, and the request id to quote to support.

When a request fails, the API returns a non-2xx HTTP status and a consistent error envelope. Read the HTTP status for the category and the `error.code` for the specific, stable reason.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API-key management requires admin role.",
    "details": { "...": "..." }
  },
  "meta": { "request_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }
}
```

| Field             | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| `error.code`      | Stable, machine-readable code — branch on this, not on the message.      |
| `error.message`   | Human-readable explanation, safe to surface in logs.                     |
| `error.details`   | Optional object with extra context (e.g. which field failed validation). |
| `meta.request_id` | Unique id for this request. Quote it when contacting support.            |

## Status codes

| Status                  | Meaning                                                             | What to do                                                                       |
| ----------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `400` Bad Request       | Malformed request or invalid parameters.                            | Fix the request shape or values.                                                 |
| `401` Unauthorized      | Missing, malformed, expired, or revoked credential.                 | Check the `Authorization` header and [your API key](/developers/authentication). |
| `403` Forbidden         | Authenticated, but the key lacks access to this resource or action. | Confirm the action is allowed for your tenant.                                   |
| `404` Not Found         | The resource doesn't exist, or isn't yours.                         | Check the id; the API never reveals other tenants' resources.                    |
| `409` Conflict          | The request conflicts with current state.                           | Re-read the resource and retry.                                                  |
| `422` Unprocessable     | The request was well-formed but semantically invalid.               | See `error.details` for the offending field.                                     |
| `429` Too Many Requests | You've hit the [rate limit](/developers/rate-limits).               | Back off and retry after `Retry-After`.                                          |
| `5xx` Server Error      | Something went wrong on Neo's side.                                 | Retry with backoff; if it persists, contact support with the `request_id`.       |

<Tip>
  Treat any `4xx` as a bug in the request to fix, not to retry blindly — except `429`, which you should retry after the `Retry-After` delay. Retry `5xx` with exponential backoff.
</Tip>

## What's next

<Card title="Rate limits" icon="gauge-high" href="/developers/rate-limits">
  How much you can call, and how to stay under the limit.
</Card>