application/problem+json. É um objeto JSON com os mesmos campos, qualquer que
seja o problema. Isso permite um único tratador de erro no seu código, em vez de
um if por endpoint.
Formato do corpo
Códigos de resposta
Sucesso
Erro
O
type completo é o valor da tabela precedido de
https://docs.cpluschat.com/errors/.
O 401 não tem corpo
Falha de autenticação é a única exceção ao formato. Ela devolve 401 com corpo
vazio e o cabeçalho WWW-Authenticate: X-Chave-Api realm="CPlus". Não há JSON
explicando o motivo, o que é deliberado, para não revelar se uma conta existe.
Trate o 401 pelo código de status e siga o
checklist de autenticação.
O 404 também significa “de outra conta”
Cada chave alcança só os dados da própria conta. Se você usar um ID válido de
outra conta, a resposta é 404, e não 403. Do ponto de vista da sua chave, o
registro não existe. O que foi excluído também responde 404.
O 422 diz qual campo está errado
O 422 traz um campo extra, errors, com o nome do campo problemático e a lista
de mensagens:
422.
O 409 é conflito de estado, não de dados
O 409 aparece quando o registro existe mas está em um estado que não aceita a
operação. Exemplos reais da API:
- cancelar uma ação agendada já executada ou já cancelada
- alterar uma ação agendada que não está mais em
Agendada - criar um produto com um
CodigoPrincipalque já existe na conta - excluir um registro que ainda está em uso por outro
detail diz qual é o caso. Como o estado pode mudar entre a sua leitura e a sua
escrita, o tratamento certo é reler o registro e decidir de novo, em vez de
repetir a mesma chamada.
Estratégia de repetição
Ao repetir, respeite duas regras.
Use espera exponencial com variação aleatória, algo como 1s, 2s, 4s, 8s, mais
alguns milissegundos de ruído. Repetição imediata em laço piora o
429.
E cuidado com repetição de escrita. POST não é idempotente. Se a criação deu
certo e a resposta se perdeu no caminho, repetir cria um registro duplicado. Em
envio de mensagem, preencha MessageId com um identificador seu para reconhecer a
duplicata. Nos demais casos, releia antes de recriar.
Erros de servidor e suporte
O500 inclui um campo traceId: