Erros

Toda resposta 4xx e 5xx da REST usa o mesmo formato, definido pela RFC 9457, com Content-Type: application/problem+json.

{
  "type": "https://docs.radar.kitelife.com.br/errors/window-too-large",
  "title": "Janela grande demais",
  "status": 422,
  "code": "Series.WindowTooLarge",
  "detail": "resolution=1m aceita no máximo 7 dias; foram pedidos 31.",
  "instance": "GET /v1/stations/stn_barra-da-tijuca-01/series",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Em que campo programar

No code. Ele é estável, legível e específico, no formato Recurso.Motivo. O type também é estável e serve ao mesmo propósito, com a vantagem de ser uma URL que abre a explicação.

Nunca no title nem no detail. São textos para humanos: mudam de redação, podem ser traduzidos, e detail varia a cada ocorrência.

O status HTTP sozinho raramente basta, já que dois erros diferentes compartilham um 422 e pedem tratamentos diferentes.

Códigos

Código	Status	Significa
ApiKey.NotRecognized	401	Chave ausente, inválida ou revogada
Station.NotFound	404	Estação inexistente, ou fora do escopo da sua chave
Station.NoReadings	404	Estação existe, mas nunca publicou
Series.WindowTooLarge	422	Intervalo maior que o teto da resolução pedida
Series.InvalidWindow	422	to anterior a from
Request.RateLimited	429	Cota excedida, ver limites

Novos códigos podem aparecer sem aviso: trate o desconhecido pelo status HTTP e registre o code no seu log em vez de falhar.

O 404 que na verdade é permissão

Pedir uma estação que existe, mas não está no escopo da sua chave, devolve 404, não 403.

É deliberado. Responder 403 confirmaria que a estação existe para outra pessoa, e o catálogo de quem tem estação onde é informação de negócio. Se você recebe 404 numa estação que deveria enxergar, o problema é de escopo da chave, não de id errado: fale conosco.

traceId

Todo erro traz um traceId. Guarde-o no seu log: com ele encontramos a requisição exata nos nossos rastros, o que transforma “deu erro ontem à tarde” em algo investigável.

Repetir ou não

Status	Repetir?
401, 404, 422	Não. Repetir dá o mesmo resultado, corrija a requisição
429	Sim, depois do tempo em Retry-After
500, 502, 503, 504	Sim, com espera crescente e aleatorizada

Repetir um 429 antes do Retry-After não adianta e conta contra a sua cota.

Nos erros de servidor, use espera exponencial com um teto: 1 s, 2 s, 4 s, até 30 s, com desvio aleatório. Sem o desvio, todos os clientes que falharam juntos voltam juntos, e o segundo pico costuma ser pior que o primeiro.

Erros nos outros canais

No WebSocket, o erro chega como mensagem error com o mesmo vocabulário de code, e não encerra a conexão salvo se fatal for verdadeiro.

No AMQP não há canal de erro: uma mensagem que o seu consumidor não processa é rejeitada por você e vai para a fila morta. Ver Relay AMQP.