Pular para o conteúdo
quebragalho/docs

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

StatuscodeO que fazer
400invalid_requestCorpo fora do formato. Confira o JSON e os campos.
400max_tokens_exceeds_capBaixe o max_tokens para o teto do seu plano.
400context_length_exceededA conversa não cabe no contexto do modelo. Encurte ou compacte.
400content_policy_violationO provedor recusou o conteúdo do pedido.
401invalid_api_keyKey ausente, revogada ou inválida. Crie outra no painel.
402insufficient_balanceO saldo livre não cobre a reserva. Recarregue.
402insufficient_paid_balanceO modelo só aceita saldo recarregado, e o recarregado não cobre.
403model_not_allowedA key tem uma lista de modelos que não inclui este.
404model_not_foundId fora do catálogo. Consulte GET /v1/models.
429rate_limit_exceeded, concurrency_limit_exceededLimite por minuto ou de pedidos simultâneos. Espere o Retry-After.
502 · 504upstream_error, timeoutFalha ou demora do provedor. Chegam como 503; tente de novo em instantes.
503wallet_unavailableInstabilidade 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.