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

# Errors

> Handle Prism inference errors, rate limits, timeouts, and retries.

## Error format

Prism returns an OpenAI-compatible error envelope:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "message": "The requested model does not exist.",
    "code": "model_not_found"
  }
}
```

Anthropic Messages clients receive the corresponding Anthropic error shape.
Use the HTTP status as the primary retry signal.

## Status codes

| Status | Meaning                                                        | Retry                                    |
| ------ | -------------------------------------------------------------- | ---------------------------------------- |
| `400`  | The body, parameter, message sequence, or model ID is invalid. | No. Correct the request first.           |
| `401`  | The API key is missing, invalid, expired, or revoked.          | No. Correct the credential first.        |
| `403`  | The key cannot access the requested model or operation.        | No. Change access or the request.        |
| `404`  | The endpoint or model was not found.                           | No. Check the URL and model ID.          |
| `408`  | The server timed out while receiving the request.              | Yes, if the operation is safe to repeat. |
| `413`  | The request body or model context is too large.                | No. Reduce the input.                    |
| `422`  | The body is well-formed but cannot be processed.               | No. Correct the input.                   |
| `429`  | A request or token rate limit was exceeded.                    | Yes, after `Retry-After`.                |
| `500`  | Prism encountered an unexpected internal error.                | Yes, with backoff.                       |
| `502`  | An upstream inference worker returned an invalid response.     | Yes, with backoff.                       |
| `503`  | Inference capacity is temporarily unavailable.                 | Yes, with backoff.                       |
| `504`  | An upstream inference request timed out.                       | Yes, with backoff.                       |

## Rate limits

For `429`, wait for the `Retry-After` delay when present. If the header is
missing, use exponential backoff with jitter.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const delay = (attempt: number, retryAfter: string | null): number => {
  if (retryAfter != null) {
    const seconds = Number(retryAfter);
    if (Number.isFinite(seconds)) {
      return Math.max(0, seconds * 1000);
    }
  }

  const exponential = Math.min(30_000, 500 * 2 ** attempt);
  return Math.random() * exponential;
};
```

Immediate retries add load and usually fail again. Cap the number of attempts
and surface the final error to the caller.

## Retry policy

Retry `408`, `429`, `500`, `502`, `503`, and `504` when the request is safe to
repeat. Do not retry other `4xx` responses until you change the request or
credential.

For streaming requests, distinguish between:

* A connection that failed before any content was consumed. Retrying is usually
  safe.
* A connection that failed after partial content was consumed. Treat the
  partial generation as interrupted or begin a new turn. Do not silently append
  a retry to it.

## Common fixes

| Error                     | Check                                                                          |
| ------------------------- | ------------------------------------------------------------------------------ |
| `model_not_found`         | Use an ID from the [model catalog](/models).                                   |
| `context_length_exceeded` | Remove old turns, reduce attached context, or choose a larger-context model.   |
| `invalid_api_key`         | Confirm the key is loaded server-side and the authorization header is present. |
| `invalid_request_error`   | Check required fields, message roles, tool schemas, and `response_format`.     |
| `rate_limit_exceeded`     | Honor `Retry-After`, reduce concurrency, and add jittered backoff.             |

Log the request ID from response headers when reporting a persistent server
error. Never log the API key or full prompts containing secrets.