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

# Errors and retries

> Handle validation, authentication, billing, rate, and provider failures.

Before an OpenAI-compatible stream begins, API errors use this structure:

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or expired.",
    "type": "invalid_request_error",
    "param": null
  }
}
```

This is an illustrative authentication error. Match the HTTP status and machine-readable `code`; do not parse human-readable error messages.

## Status guide

| Status | Typical cause | Action |
| - | - | - |
| `400` | Invalid JSON, missing model/input, unsupported feature, or provider rejection. | Correct the request before retrying. |
| `401` | Missing, invalid, expired, or revoked customer key. | Check or replace the key. |
| `402` | Available credits or spending allowance cannot cover admission. | Review Billing and Limits. |
| `403` | Missing key scope, insufficient console role, or an enforcing policy match. | Check permissions or the policy error code. |
| `404` | Missing route or unavailable model. | Check the path and model catalog. |
| `409` | Stale policy revision, conflicting idempotency key, or invalid resource state. | Retrieve the current resource before another mutation. |
| `405` | Unsupported HTTP method. | Use the method listed in the `Allow` header. |
| `408` | Request-body upload did not finish in time. | Check the client connection. |
| `413` | Request body exceeds 8 MiB. | Reduce the payload. |
| `415` | Content type is not JSON. | Send `Content-Type: application/json`. |
| `429` | Workspace limit or upstream capacity exceeded. | Respect `Retry-After` when present and back off. |
| `500` | Unexpected server failure. | Keep the request ID and inspect Activity before replaying. |
| `502` | Inference backend failed. | Retry only when appropriate for your workflow. |
| `503` | Required service/configuration or usage persistence is unavailable. | Wait or contact the beta operator. |
| `504` | Inference exceeded the gateway deadline. | Review Activity and reduce the workload if needed. |

Common stable codes include `invalid_request`, `invalid_model`, `unsupported_feature`, `provider_rejected_request`, `rate_limited`, `provider_unavailable`, `usage_unavailable`, and `inference_timeout`. Backend details and credentials are not included in error messages.

Prepaid admission uses these more specific codes:

| Code | Status | Meaning |
| - | - | - |
| `insufficient_credit` | `402` | Available wallet funds cannot cover the reservation. |
| `monthly_budget_exceeded` | `402` | The monthly cap cannot cover another reservation. |
| `rate_limit_exceeded` | `429` | The workspace has exhausted its rolling request allowance. |
| `concurrency_limit_exceeded` | `429` | The workspace's concurrent request slots are occupied. |
| `model_unavailable` | `400` | The requested model is absent from the enabled price catalog. |
| `model_not_priced` | `503` | Model pricing became unavailable during database admission. |

## Streaming errors

After HTTP headers have been sent, the server cannot replace the response with a different status. A stream may end early or carry a provider failure event. Catch SDK iteration errors, inspect terminal events, and check Activity; a `200` alone does not prove completion.

## Retry deliberately

The gateway performs no automatic upstream inference retries. The official SDKs may retry some failures unless you set JavaScript `maxRetries: 0` or Python `max_retries=0`, as in the quickstart.

Inference POST requests are not deduplicated by an idempotency key. Replaying a request can generate another response and incur another charge, even if the first response was lost in transit. For interactive applications, show an explicit retry action after partial output. For jobs, store your own job state and use bounded exponential backoff with jitter.

Capture `X-Request-ID` for diagnosis. Never include your API key in logs or support messages.

## Messages, administration, and policies

Messages errors add a top-level `type: "error"` and use Anthropic-style categories such as `authentication_error` and `rate_limit_error`. Continue matching the HTTP status and `error.code`.

Administrative errors and policy errors include `error.request_id`. A stale policy revision returns `409` with `policy_revision_conflict`; read the latest revision before editing. Creation retries must keep the same idempotency key and payload. An expired key-secret replay window returns `idempotency_reconciliation_required`; inspect existing keys before issuing another.

A blocking policy can return `policy_violation`; an unavailable evaluator can return `policy_evaluation_unavailable`. These use `policy_error`. Do not silently disable a policy to retry an otherwise rejected request.


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