Tratamento de erros
Códigos de erro e como tratá-los
Todas as respostas de erro seguem este formato:
json
{
"error": {
"code": "machine_readable_code",
"message": "Human-readable description in English."
}
}Códigos comuns
| Status | Código | Significado | |
|---|---|---|---|
| 400 | invalid_request | — | Body inválido ou campos malformados. |
| 401 | unauthorized | — | API key ausente, inválida ou revogada. |
| 402 | quota_exceeded | — | Sem storage suficiente. |
| 403 | forbidden | — | Key sem o scope exigido. |
| 403 | plan_restricted | — | Recurso exige plano superior. |
| 404 | not_found | — | Recurso não existe ou não é seu. |
| 429 | rate_limited | — | Muitas requests. Respeite Retry-After. |
| 500 | internal_error | — | Erro nosso. Reintente com backoff. |
Política de retry
Recomendações de retry por status:
- 4xx (exceto 429): NÃO reintente. O erro é permanente até você mudar algo (corrigir body, gerar nova key, comprar mais storage).
- 429: respeite o header Retry-After. Implemente backoff exponencial.
- 5xx: reintente com backoff (1s, 2s, 4s, 8s, 16s). Se persistir >5 min, abra um ticket.
Recomendado: logue o code (machine-readable) no seu sistema, não a message. Mensagens estão em inglês e podem mudar; códigos são estáveis.