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

# Errors

> Typed, machine-parseable failures with an explicit retryable flag, exactly what a retry loop wants

Errors here are boring on purpose. Every failure returns one JSON object with
a stable shape and an explicit answer to the only question an agent has: do I
retry this or not?

```json theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "...",
    "retryable": false,
    "request_id": "..."
  }
}
```

`retryable` is an explicit boolean: `true` means the same request can succeed
if you retry, `false` means it will not, ever. `request_id` is a correlation
ID that is safe to share with support. Error responses never charge data
credits, though they do spend a rate unit.

## Status codes

| HTTP | Code                   | Retryable | Meaning                                               |
| ---- | ---------------------- | --------- | ----------------------------------------------------- |
| 400  | `invalid_parameter`    | No        | No valid request can be formed from the parameters    |
| 401  | `unauthenticated`      | No        | Personal key missing or invalid                       |
| 402  | `quota_exhausted`      | No        | No data credits remaining                             |
| 405  | `method_not_allowed`   | No        | A non-GET method was used on an HTTP operation        |
| 409  | `idempotency_conflict` | No        | An idempotency key was reused for a different request |
| 409  | `request_in_progress`  | Yes       | A duplicate request is already in flight              |
| 429  | `rate_limited`         | Yes       | Rate admission denied                                 |
| 500  | `internal_error`       | No        | An unclassified server failure                        |
| 503  | `upstream_unavailable` | Yes       | A required boundary is unavailable                    |
| 504  | `timeout`              | Yes       | No valid response before the deadline                 |

## What to do

Fix the request for the non-retryable codes. For `invalid_parameter`, correct
the parameters against the operation's `schema`. For `unauthenticated`, check
that a valid `nx_` key is in the `Authorization` header. For
`quota_exhausted`, fund your key with a data-credit pack from the console
(packs open with the API beta). For `method_not_allowed`, switch to GET,
since every HTTP operation is a GET request. For `idempotency_conflict`, use
a new key, since each key is bound to one request for 24 hours.

The `internal_error` code is an unclassified server failure and is not marked
retryable. Do not retry it blindly. Capture the `request_id` and share it
with support.

Retry the retryable codes with backoff. For `rate_limited` and
`request_in_progress`, honor the `Retry-After` header. For
`upstream_unavailable` and `timeout`, retry after a short delay. Reusing the
same idempotency key on these retries is safe: a transient failure releases
the hold, so the retry runs once and settles once.

## Deadlines and limits

The gateway uses a 15-second upstream deadline and a 2 MiB response limit. A
request that exceeds the deadline returns `timeout`. These bounds also keep
error responses small and fast, so retry logic can rely on them.