Resumo

  • A RFC 7807, de março de 2016, padronizou uma forma JSON e XML para detalhes de problemas HTTP. A URI type já era a identidade principal para consumidores automáticos.
  • A RFC 9457, de julho de 2023, substituiu a anterior e explicitou riscos de URIs relativas, mudanças de identidade e problemas simultâneos.
  • O registro da IANA reúne tipos comuns. Quando type não aparece, about:blank limita o significado ao próprio código HTTP.

O recibo de recusa que não explica a recusa

HTTP 403 diz ao navegador, ao proxy e à biblioteca de rede que a solicitação foi proibida. Essa informação é suficiente para tratamento genérico, mas uma loja precisa distinguir falta de saldo de outras regras. Criar um código HTTP para cada condição comercial destruiria a utilidade do vocabulário comum. A RFC 7807 resolveu a divisão de trabalho: o status continua no protocolo, enquanto o corpo identifica o problema que a aplicação conhece.

No exemplo da norma, uma compra falha com 403 e o corpo descreve falta de crédito. Há um título legível, uma explicação da ocorrência, uma URI para a instância e campos adicionais com saldo e contas. O envelope application/problem+json é compartilhado, assim como a alternativa XML; a regra específica de crédito pertence a quem publica a API. A especificação não podia decidir por todas as lojas qual resposta comercial seguir.

O campo type é a parte que um cliente pode reconhecer de modo estável. Desde 2016, a norma manda tratá-lo como identificador principal do tipo de problema. title serve às pessoas e pode variar conforme o idioma. detail narra aquela ocorrência e não deve virar fonte de instruções por busca de palavras. Se o aplicativo procura “saldo” dentro de uma frase, uma tradução basta para alterar seu comportamento. Reconhecer uma URI transfere a dependência para um contrato explícito com o operador.

instance representa outra coisa: o episódio individual. Duas compras sem crédito podem compartilhar type e ter instâncias distintas. O atendimento precisa localizar o episódio; o software precisa reconhecer a classe de falha. Tratar ambos como um único “código de erro” esconde a diferença entre um diagnóstico reutilizável e um registro particular.

O significado de deixar o campo vazio

Quando falta type, a norma presume about:blank. O nome informa uma decisão sóbria: o problema não acrescenta significado ao status HTTP. Um 404 embalado em JSON continua sendo um 404. Para exigir que programas distingam uma causa específica, a API precisa nomeá-la. A uniformidade do formato não substitui a responsabilidade de definir a semântica.

O membro status no corpo também não governa a mensagem HTTP. Ele é informativo e, se for incluído, deve coincidir com o status real da resposta. Um intermediário pode criar divergência, e um corpo arquivado pode perder a linha de status original; programas HTTP genéricos continuam guiados pelo código da resposta. O detalhamento da aplicação convive com esse limite.

A mudança de endereço cobra seu preço

Em 2023, a RFC 9457 manteve o modelo e descreveu o risco de dar uma URI relativa ao tipo. A mesma grafia pode se resolver em endereços diferentes conforme a URL de base. A revisão recomenda URIs absolutas quando possível. Também admite identificadores que não abrem uma página. Se o operador decide mais tarde trocá-los por um URL consultável, troca a identidade do problema; clientes antigos podem deixar de reconhecer a falha.

A revisão trata ainda de várias falhas na mesma resposta. Uma validação pode incluir uma lista de campos inválidos sob um único tipo. Quando tipos diferentes disputam o diagnóstico, convém apresentar o mais relevante ou urgente. A resposta HTTP carrega um status; uma sacola de diagnósticos desconexos não orienta a próxima ação.

O registro IANA criado pelo sucessor recebe tipos amplamente compartilháveis sob exigência de especificação. Tipos restritos a uma aplicação ficam com o seu publicador. Para contar adoção histórica faltam respostas preservadas e versões datadas dos clientes. Os dois documentos já deixam claro quem assume a promessa: quem põe no mundo o endereço de uma falha.