Pular para conteúdo

0015 — Erro da API em RFC 7807

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

Contexto

O corpo de erro do /api/** saía no shape default do Micronaut (Hateoas, {message, _links}). O padrão da casa para erro de API é RFC 7807 / 9457 (application/problem+json) — padrão IETF, já adotado no irmão bi-transporte-xls (decisão viva 0021 daquele projeto). Este app era o outlier; alinhar reduz custom e faz futuros consumidores herdarem o mesmo formato.

Decisão

Erro de API no formato RFC 7807. Um ErrorResponseProcessor que @Replaces o Hateoas default emite o shape 7807 + Content-Type: application/problem+json, com o record ProblemDetail (@Serdeable) e security/AuthExceptionHandler para os erros de autenticação. Todo erro do /api/** sai como problem+json; os status HTTP são preservados (contratos 409/404/503 intactos). Teste de contrato em api/RfcProblemDetailTest.

Atualização (spec 009 / ADR 0019): o processor e o ProblemDetail não são mais cópias locais — vêm da lib br.com.xadm:xadm-comum-web:0.1.0, junto com /health, /info (VersaoInfo) e o SentryInitializer. Comportamento HTTP idêntico; muda só a procedência do código (import br.com.xadm.comum.web).

Consequências

  • Contrato de erro padrão, interoperável, alinhado à casa e ao app irmão.
  • Outward-facing: o corpo de erro do /api/** mudou de {message, _links} para problem+json — consumidores que liam message passam a ler detail. Avisar quem integra.
  • Menos custom no longo prazo; sem dependência nova (reusa o processor que já substituía o Hateoas).

Alternativas consideradas

  • Manter o default Hateoas ({message, _links}): divergente do padrão da casa, sem vantagem real. Descartado.
  • Módulo micronaut-problem-json (Zalando): dá os tipos/exceções 7807 prontos, mas adiciona dependência + modelo de exceção próprio; para middleware interno, o shape 7807 via o processor existente é mais leve. Descartado por ora.