API reference

Errors and limits

Error format

Errors use the format of the route that was called. In /v1/chat/completions, type and code carry the same code. Messages are in Portuguese.

OpenAI · /v1/chat/completions

{
  "error": {
    "message": "Saldo insuficiente.",
    "type": "sem_saldo",
    "code": "sem_saldo"
  }
}

Anthropic · /v1/messages

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Saldo insuficiente."
  }
}

HTTP	Code	Cause
400	`invalido`	Invalid JSON, missing messages, n other than 1, or a parameter rejected by the model.
400	`sem_visao`	Image sent to a model without vision.
401	`chave_invalida`	Missing, malformed or unknown key.
401	`chave_revogada`	Key revoked in the console.
401	`chave_expirada`	Key past its expiration date.
402	`sem_saldo`	Balance lower than the request reserve.
402	`teto_chave`	Key daily or monthly cap reached.
403	`termos`	Terms of use not yet accepted in the console.
403	`restrito`	Account without API access yet. Until launch, the API serves the team only.
403	`modelo_nao_permitido`	Model not in the key's allowed list.
403	`conta_bloqueada`	Account blocked.
404	`modelo`	Model not found. The message lists the available IDs.
413	`grande`	Request body above the limit.
429	`limite_minuto`	Key requests-per-minute limit.
429	`muitas_falhas`	Too many attempts with an invalid key from the same IP. Includes Retry-After.
429	`limite_provedor`	Model overloaded. Try again shortly.
502	`provedor`	Failed to reach the model, or invalid response.
503	`indisponivel`	Service unavailable.

In /v1/messages, error.type follows the HTTP status:

Limit	Value	When exceeded
Requests per key	60 per minute	`429 limite_minuto`
Invalid-key attempts per IP	20 in 10 minutes	`429 muitas_falhas`
Request body	4 MB	`413 grande`
Request duration	300 seconds	—
Responses per request (n)	1	`400 invalido`
Key spend	Daily and monthly cap, optional	`402 teto_chave`
Balance	Reserve per request	`402 sem_saldo`

The per-minute limit counts the last 60 seconds of each key. muitas_falhas returns the Retry-After header, in seconds.

A request the model answers with an HTTP error, or that never reaches the model, is not billed. See Billing.