Referência da API
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
{ "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 e Responses.
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_tokensdeGET /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/usagee/v1/status.