Erros

Erros e rate limits

Cada resposta de erro usa o mesmo envelope JSON para que o cliente possa decidir com base num código estável em vez de fazer parse de mensagens livres.

Envelope de erro

Os erros vêm sempre em application/json com status HTTP e um código estável. Localiza a mensagem para o utilizador final; nunca decidas com base nela.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "details": { "retry_after": 12 }
  }
}

Códigos comuns

Estes são os códigos que vais ver com mais frequência em produção.

Status	Code	Description
401	unauthorized	Cabeçalho Authorization em falta ou inválido.
403	forbidden	Autenticado mas sem permissão para este recurso.
404	not_found	Recurso inexistente ou removido.
422	invalid_request	Corpo falhou validação. Vê o campo details.
429	rate_limited	Demasiados pedidos. Aguarda e repete.
500	internal_error	Erro inesperado no servidor. Seguro repetir com backoff.

Rate limits

/v1/serve e /v1/track têm rate limits agressivos por chave SDK e por IP. Endpoints autenticados são limitados por sessão. Ao exceder o limite devolvemos 429 com Retry-After em segundos.