Pular para conteúdo

Erros de API — RFC 7807 (application/problem+json)

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-10

Todo corpo de erro gerado pelo framework (Bean Validation, 404 de rota, parse de corpo, HttpStatusException) é formatado no formato RFC 7807 por um ponto único — substitui o envelope custom antigo {status, error, message}.

{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "…", "code": "NOT_FOUND" }
  • ProblemDetail (br.com.xadm.comum.web, da lib da casa xadm-comum-web — decisão 0017) — record {type, title, status, detail, code, invalid-params}. code é a extensão 7807 com o código estável legível por máquina; invalid-params (lista de {name, reason}) só aparece na falha de Bean Validation, que sai com code BAD_REQUEST.
  • UnifiedErrorResponseProcessor (mesma lib) — @Replaces o HateoasErrorResponseProcessor default; formata o corpo (não decide o status) com Content-Type: application/problem+json e loga todo erro: 5xx e 404 autenticado em ERROR (vão ao GlitchTip), o resto em DEBUG.
  • O GlobalExceptionHandler (500; para browser serve página HTML, fluxo especial) e o ViewRejectionHandler (auth) emitem o mesmo shape.

Exceções deliberadas ao processor

/api/v1/xadm. O endpoint XADM não usa esse processor: o 400 de JSON malformado é produzido no controller (XadmResponse), e JSON válido sempre responde 200 com o resultado no corpo — contrato com o agente on-prem, inalterado. Ver tratamento de erros XADM.

/api/v1/heartbeat. O HeartbeatController monta os próprios erros (503 heartbeat_desligado, 502 heartbeat_recusado, 502 central_indisponivel — contrato) como ProblemDetail à mão, no molde do ViewRejectionHandler, em vez de lançar exceção. Duas razões: o processor loga todo 5xx em ERROR — o 502 transitório (central fora) viraria uma issue por hora em cada instância, e ele tem de ficar em WARN — e devolve o nome do status como code, não os códigos do contrato. O 400 de validação do heartbeat continua sendo do processor. Porquê e alternativas: decisão 0026.

Código: ProblemDetail e UnifiedErrorResponseProcessor na lib; comum/{GlobalExceptionHandler, ViewRejectionHandler}; heartbeat/HeartbeatController. Teste: comum/{UnifiedErrorResponseProcessorTest, GlobalExceptionHandlerTest}, heartbeat/*Test.