Mensagens de erro de API segundo a RFC 9457 (Problem Details)

O que é

A RFC 9457 substitui a RFC 7807 e descreve um objeto JSON que o servidor envia, com o tipo de mídia application/problem+json (ou application/problem+xml), como corpo da resposta em caso de erro. Os campos são: type – uma URI que identifica a classe do erro e que, idealmente, devolve uma descrição quando acessada; se estiver ausente, vale about:blank. title – um resumo curto, igual para todas as ocorrências dessa classe. status – o código de status HTTP como número. detail – uma explicação desta ocorrência concreta. instance – uma URI que identifica esta ocorrência. Campos de extensão próprios («extension members») são expressamente previstos, por exemplo uma lista de erros de campo na validação.

Por que importa

O código de status sozinho é grosseiro demais: duas respostas 409 podem significar «versão desatualizada» e «nome já em uso» e exigem reações diferentes. Um cliente capaz de ramificar por type decide entre tentar de novo, recarregar ou desistir sem precisar analisar um texto de mensagem que muda na versão seguinte. Para agentes que usam APIs a partir da documentação, um catálogo de erros estável e documentado é a condição para não precisarem adivinhar.

Como aplicar

• Um único formato de erro para todas as respostas fora da faixa 2xx, definido uma vez na descrição OpenAPI e referenciado por todos os endpoints.
• Uma URI type estável por classe de erro, sob o próprio domínio (por exemplo https://api.example.ch/probleme/kontingent-erschoepft), apontando para uma página com o significado, o status típico e a reação recomendada; essa lista pertence à documentação da API.
• type e title permanecem estáveis entre versões; só detail descreve o caso individual e não devolve inalterados os dados informados pelo usuário.
• Transmitir as indicações de nova tentativa em cabeçalhos padrão (Retry-After); o objeto de problema pode mencioná-las adicionalmente.
• Erros de validação como campo de extensão, com uma lista contendo caminho do campo, tipo de erro e mensagem, para que o cliente possa exibir todas as falhas de uma só vez.
• O status no corpo deve corresponder ao status HTTP realmente enviado; a RFC classifica o campo como consultivo, para que o cliente conheça o status original mesmo que um intermediário o tenha alterado.

Armadilhas

Stack traces, nomes de host internos ou SQL em detail. Status 200 com um objeto de erro no corpo, o que engana caches e clientes igualmente. Renomear classes de erro sem período de transição. Uma URI type que aponta para uma página 404. Introduzir o formato só em alguns endpoints, de modo que os clientes precisem de dois parsers.