> Index: https://quebragalho.dev/en/docs/llms.txt

# Errors and limits

The error format, what each code means and the API limits: balance hold, output cap, requests per minute and concurrency.

## An error object with a code

Each route answers in the error format of the API it mirrors. On `/v1/chat/completions` it is OpenAI's: an `error` object with `message`, `type` and `code`. Read the `code`, not just the status.

**Response · 400**

```json
{
  "error": {
    "message": "max_tokens exceeds plan limit",
    "type": "invalid_request_error",
    "code": "max_tokens_exceeds_cap"
  }
}
```

The Anthropic format (`/v1/messages`) and the Responses format have their own tables: see [Messages](https://quebragalho.dev/en/docs/api/messages.md#erros) and [Responses](https://quebragalho.dev/en/docs/api/responses.md#erros).

## The most common codes

| Status | code | What to do |
| --- | --- | --- |
| 400 | `invalid_request` | Malformed body. Check the JSON and the fields. |
| 400 | `max_tokens_exceeds_cap` | Lower `max_tokens` to your plan's cap. |
| 400 | `context_length_exceeded` | The conversation does not fit the model's context. Shorten or compact it. |
| 400 | `content_policy_violation` | The provider refused the request's content. |
| 401 | `invalid_api_key` | Missing, revoked or invalid API key. Create another one in the dashboard. |
| 402 | `insufficient_balance` | Your available balance does not cover the hold. Top up. |
| 402 | `insufficient_paid_balance` | The model only accepts topped-up balance, and your topped-up balance does not cover it. |
| 403 | `model_not_allowed` | The key has a model list that does not include this one. |
| 404 | `model_not_found` | Id outside the catalog. Query `GET /v1/models`. |
| 429 | `rate_limit_exceeded`, `concurrency_limit_exceeded` | Per-minute or concurrent-request limit. Wait for `Retry-After`. |
| 502 · 504 | `upstream_error`, `timeout` | Provider failure or slowness. They arrive as 503; try again shortly. |
| 503 | `wallet_unavailable` | A brief hiccup on our side. Wait for `Retry-After`. |

> 502 and 504 responses arrive as 503: Cloudflare, in front of the API, swaps those statuses. Read the type and the `code` in the body, not just the status.

## Hold, cap and pace

- `Hold`: Before each response, your balance sets aside a hold based on the request size and the output cap. At the end, it charges only what was generated and returns the rest.
- `Output cap`: Each plan has an output cap per model. The one that applies to your key is in the `max_output_tokens` field of `GET /v1/models`.
- `Per minute and concurrent`: The requests-per-minute and concurrent-request limits come from your plan. Above them, 429 with `Retry-After`.
- `Account API`: Up to 60 reads per minute per key on `/v1/balance`, `/v1/key`, `/v1/usage` and `/v1/status`.

Read it in the browser: https://quebragalho.dev/en/docs/api/erros
