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

# Errors and troubleshooting

> Handle authentication, credit, capacity, and streaming failures.

Check the HTTP status before reading a normal response. With streaming, also inspect error events after the connection has opened.

## HTTP errors

| Status | Meaning                                                                                                     | Next step                                                                         |
| ------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `400`  | Invalid request, unsupported option, or context-length error.                                               | Check the endpoint format, shorten the request, and remove unsupported fields.    |
| `401`  | API key is missing, malformed, invalid, expired, or revoked.                                                | Check the key and authentication header.                                          |
| `402`  | Insufficient available credit for the request.                                                              | Check your console balance; reduce input/output allowance or request more credit. |
| `403`  | Account is inactive or its email is unverified.                                                             | Check the account in the console.                                                 |
| `404`  | The requested route or capability is unavailable.                                                           | Check the base URL and the supported endpoint list.                               |
| `413`  | Request body or input bound exceeds a limit.                                                                | Reduce conversation history and tool definitions.                                 |
| `429`  | Rate, concurrency, input-volume, or shared-capacity limit.                                                  | Wait before retrying and reduce concurrent work.                                  |
| `502`  | Upstream generation or transport failed.                                                                    | Retry with backoff if the operation can safely be repeated.                       |
| `503`  | Credit is activating, the account's upstream key is unavailable, or the service is temporarily unavailable. | Follow `Retry-After` when present.                                                |
| `504`  | Generation exceeded a timeout.                                                                              | Retry with a smaller request or output allowance.                                 |

An apparently sufficient displayed balance can still produce `402` if concurrent requests have reserved credit or the requested output allowance is too large. The check reserves enough for the allowed request before generation starts.

## Error bodies

Chat Completions and Responses normally use an OpenAI-style error object. For example:

```json theme={"system"}
{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

Messages normally uses an Anthropic-style error envelope:

```json theme={"system"}
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Incorrect API key provided."
  }
}
```

Handle the status even if an infrastructure or route-level error has a different JSON shape. Useful OpenAI-style codes include `invalid_api_key`, `insufficient_credits`, `credit_pending`, `key_unavailable`, `too_many_concurrent`, and `input_too_large`. Messages clients should also inspect the error type and message; the same code field is not always present.

## Retry behavior

Honor `Retry-After` when supplied. For temporary `429`, `502`, `503`, and `504` failures, use capped exponential backoff and avoid starting many retries at once. Repeating an inference request can generate a new answer and incur additional usage; inference requests do not expose an idempotency-key guarantee.

`credit_pending` usually means a new grant or credit update is still being activated. Wait a few seconds and retry. An exhausted balance needs additional credit; repeatedly signing in or creating keys does not refill it.

## Streaming errors

Once streaming starts, the HTTP status can remain `200` even if generation later fails:

* **Chat Completions:** an SSE `data:` frame contains `error`, followed by `[DONE]`.
* **Responses:** an error event or a failed/incomplete response can terminate the result.
* **Messages:** an `event: error` frame contains the error envelope.

Keep partial text separate from a completed answer. Keepalive comments and `ping` events are not errors or output. Closing a stream cancels the upstream request, but work already performed may still be accounted for.

## Report a problem

If present, record the `x-request-id` response header, endpoint, status, and approximate time. Contact [hello@derestricted.ai](mailto:hello@derestricted.ai) with those details. Do not include an API key. Describe a reproducible request without including private prompt content when possible.