Erros & retentativas

Os erros são retornados como JSON com um código error estável e legível por máquina, e o status HTTP correspondente.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

Códigos de erro

HTTP	`error`	Repetir?	Notas
400	`invalid_request`	Não	Um parâmetro falhou na validação — corrija a requisição.
401	`missing_api_key` / `unknown_api_key`	Não	Veja Autenticação.
403	`inactive_api_key` / `account_blocked`	Não	Chave desabilitada ou conta suspensa.
402	`insufficient_credits`	Não	Adicione créditos. O corpo inclui `required` e `balance`.
429	`rate_limited`	Sim, após `retry_after_ms`	Você excedeu seu limite por minuto.
409	`request_in_progress`	Sim	Uma requisição idempotente idêntica ainda está em execução.
422	(conflito de idempotência)	Não	Uma `Idempotency-Key` foi reutilizada com um corpo diferente.
503	`service_temporarily_unavailable` / `too_many_concurrent_requests`	Sim, com backoff	Limite de capacidade transitório.
504	`result_timeout`	Sim	A busca upstream excedeu `deadline_ms`.

Repita 429 / 503 / 504 / 409 com backoff exponencial. Quando retry_after_ms estiver presente, espere pelo menos esse tempo antes de repetir.
Nunca repita 400 / 401 / 402 / 403 — a requisição não terá sucesso até que você a altere.
Os SDKs oficiais já repetem erros transitórios para você (padrão de 2 retentativas) e expõem uma flag retryable no erro.