Pular para conteúdo

0021 — Erro de API em RFC 7807

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-18 · Decidido em: 2026-06-18

Supera a decisão 0017 (corpo {code, message}), que rejeitou o RFC 7807 "por simplicidade".

Contexto

A 0017 adotou um corpo de erro custom {code, message}. Ao consolidar o padrão Micronaut da casa (skill micronaut), ficou claro que o default da casa para erro de API é RFC 7807 / 9457 (application/problem+json) — padrão IETF, e este app era o outlier. Como o app deve seguir o default da casa salvo divergência justificada (§1.6), e o {code, message} não tinha vantagem real sobre o 7807, alinha-se ao padrão.

Decisão

Erro de API no formato RFC 7807 (ProblemDetail): type (about:blank quando sem tipo específico), title (resumo do status), status (HTTP), detail (mensagem) e code (extensão — código estável legível por máquina, preserva o machine-code da 0017).

Implementação: o MN5 não traz ProblemDetail nativo (não há classe; o módulo micronaut-problem-json Zalando não está no projeto). Mantém-se o UnifiedErrorResponseProcessor (que já substituía o Hateoas default), agora emitindo o shape 7807 + Content-Type: application/problem+json. Sem dependência nova.

Atualização (0024): o ProblemDetail e o UnifiedErrorResponseProcessor foram depois extraídos para a lib xadm-comum-web (decisão 0024) — hoje vêm de br.com.xadm.comum.web, não de cópias locais. O shape 7807 e o code estável seguem idênticos; a "sem dependência nova" valia à época desta decisão.

Consequências

  • Contrato de erro padrão, interoperável; o code estável continua disponível como extensão.
  • Menos custom no longo prazo (alinha à casa; futuros apps herdam o mesmo formato).
  • O corpo de erro mudou de {code, message} para o objeto 7807 — clientes que liam message passam a ler detail. Único ponto de atenção (interno; sem cliente externo dependente hoje).

Alternativas consideradas

  • Manter {code, message} (0017): custom, divergente do default da casa, sem vantagem. Descartado.
  • Módulo micronaut-problem-json (Zalando): dá os tipos/exceções 7807 prontos, mas adiciona dependência + modelo de exceção próprio (ThrowableProblem). Para middleware interno, o shape 7807 via o processor existente é mais leve. Fica como opção se um app quiser os tipos Zalando.