Erros e novas tentativas

A forma de um erro

{
  "error": "INVALID_REQUEST",
  "field": "noticeType",
  "message": "noticeType é obrigatório"
}

Decida sempre pelo error. Ele é o código estável. O field aparece quando a recusa é atribuível a um campo, e o message é texto em português para quem está diagnosticando: pode mudar sem aviso, e programar contra ele quebra em qualquer ajuste de redação.

Os códigos

error	HTTP	O que fazer
INVALID_REQUEST	400	Corrigir o campo indicado. Repetir não ajuda
INVALID_JSON	400	O corpo não é JSON válido
NOT_FOUND	404	O recurso não existe no seu órgão
NOT_IMPLEMENTED	501	A rota existe e ainda não foi implementada
DATABASE_RESUMING	503	Repetir. Ver abaixo
INTERNAL_ERROR	500	Falha nossa. Repetir com espera crescente

Sem corpo JSON, porque a recusa acontece antes da aplicação:

HTTP	Causa
401	Faltou o cabeçalho Authorization
403	Token inválido, expirado, ou de emissor desconhecido

O 503 que não é erro

O banco de cada órgão escala a zero quando ninguém o usa. A primeira chamada depois de alguns minutos ociosos acorda o banco, e esse despertar leva alguns segundos.

Se o banco não retomar dentro do orçamento da requisição, a resposta é:

HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

{
  "error": "DATABASE_RESUMING",
  "message": "Banco de dados está retomando. Tente novamente."
}

Isto é comportamento normal, não incidente

Ambientes de homologação passam a maior parte do tempo ociosos, então é ali que você mais vai ver este código. Repita respeitando o Retry-After: a chamada seguinte costuma funcionar.

Uma integração que trate 503 como falha definitiva vai parecer instável sem motivo. Uma que repita sem espera vai só amontoar requisições enquanto o banco acorda.

Repetir com segurança

GET pode ser repetido à vontade.

POST /notices também, desde que você reenvie a mesma Idempotency-Key. É exatamente o cenário para o qual ela existe: você não sabe se o timeout aconteceu antes ou depois de o ato ser criado, e repetir com a mesma chave resolve os dois casos: devolve 200 com o registro original se ele já existia, ou cria com 201 se não.

Gerar uma chave nova na repetição cria um ato duplicado. É o erro mais caro possível aqui: significa comunicar o mesmo cidadão duas vezes.