> Índice: https://quebragalho.dev/docs/llms.txt

# Erros e limites

O formato dos erros, o que cada código quer dizer e os limites da API: reserva de saldo, teto de saída, pedidos por minuto e concorrência.

## Um objeto error com code

Cada rota responde no formato de erro da API que ela imita. Em `/v1/chat/completions` é o da OpenAI: um objeto `error` com `message`, `type` e `code`. Leia o `code`, não só o status.

**Resposta · 400**

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

O formato Anthropic (`/v1/messages`) e o formato Responses têm as próprias tabelas: veja [Messages](https://quebragalho.dev/docs/api/messages.md#erros) e [Responses](https://quebragalho.dev/docs/api/responses.md#erros).

## Os códigos mais comuns

| Status | code | O que fazer |
| --- | --- | --- |
| 400 | `invalid_request` | Corpo fora do formato. Confira o JSON e os campos. |
| 400 | `max_tokens_exceeds_cap` | Baixe o `max_tokens` para o teto do seu plano. |
| 400 | `context_length_exceeded` | A conversa não cabe no contexto do modelo. Encurte ou compacte. |
| 400 | `content_policy_violation` | O provedor recusou o conteúdo do pedido. |
| 401 | `invalid_api_key` | Key ausente, revogada ou inválida. Crie outra no painel. |
| 402 | `insufficient_balance` | O saldo livre não cobre a reserva. Recarregue. |
| 402 | `insufficient_paid_balance` | O modelo só aceita saldo recarregado, e o recarregado não cobre. |
| 403 | `model_not_allowed` | A key tem uma lista de modelos que não inclui este. |
| 404 | `model_not_found` | Id fora do catálogo. Consulte `GET /v1/models`. |
| 429 | `rate_limit_exceeded`, `concurrency_limit_exceeded` | Limite por minuto ou de pedidos simultâneos. Espere o `Retry-After`. |
| 502 · 504 | `upstream_error`, `timeout` | Falha ou demora do provedor. Chegam como 503; tente de novo em instantes. |
| 503 | `wallet_unavailable` | Instabilidade nossa e passageira. Espere o `Retry-After`. |

> As respostas 502 e 504 chegam como 503: a Cloudflare, na frente da API, troca esses status. Leia o tipo e o `code` no corpo, não só o status.

## Reserva, teto e ritmo

- `Reserva`: Antes de cada resposta, o saldo separa uma reserva pelo tamanho do pedido e pelo teto de saída. No fim, cobra só o que foi gerado e devolve o resto.
- `Teto de saída`: Cada plano tem um teto de saída por modelo. O que vale para a sua key sai no campo `max_output_tokens` de `GET /v1/models`.
- `Por minuto e simultâneos`: Os limites de pedidos por minuto e de pedidos ao mesmo tempo vêm do seu plano. Acima deles, 429 com `Retry-After`.
- `Conta pela API`: Até 60 leituras por minuto por key em `/v1/balance`, `/v1/key`, `/v1/usage` e `/v1/status`.

Versão para ler no navegador: https://quebragalho.dev/docs/api/erros
