DEV Community

Thiago Henrique Domingues
Thiago Henrique Domingues

Posted on

Problems details: A importância de mensagens de erro claras e estruturadas na sua API REST

Se você já precisou integrar sua aplicação com APIs externas, com certeza enfrentou a dificuldade de lidar com diferentes formatos de erros. Ter mensagens de erro bem estruturadas é tão importante quanto ou até mais do que retornar respostas de sucesso bem definidas.

É bastante comum cada projeto definir seu próprio padrão de retorno de erros. Em sistemas pequenos, isso pode funcionar bem, mas à medida que o número de integrações cresce, a complexidade no tratamento de exceções cresce junto. Imagine um projeto que precisa integrar com diversas APIs diferentes, e cada uma delas possui um padrão de erro diferente. Agora pense no tempo que os desenvolvedores vão gastar apenas para entender e tratar cada formato antes de resolver o problema real.

Como forma de resolver esse problema, a Internet Engineering Task Force (IETF) propôs o padrão Problem Details para retorno de erros em APIs. Ele define uma estrutura padronizada e consistente para respostas de erro, garantindo que os consumidores consigam entender e tratar falhas de forma mais simples e clara. Em vez de cada desenvolvedor ter que reinventar a roda, eles podem usar esse padrão para definir os detalhes de cada solicitação.

A estrutura do objeto Problem Details encapsula informações de erro de uma forma que pode ser universalmente compreendida em diferentes sistemas e tecnologias.

  • type: URI que identifica o tipo de problema;
  • status: Código HTTP;
  • title: resumo legível do erro;
  • detail: explicação detalhada;
  • instance: URI específica do erro ocorrido (opcional);
  • extensions: qualquer campo que adiciona informações adicionais ou contexto para o cliente que está consumindo;

Segue um exemplo de um objeto resposta que contém a propriedade de extensão errors:

{
  "type": "https://myapi.com/errors/invalid-input",
  "title": "Invalid input data",
  "status": 400,
  "detail": "One or more fields have invalid data.",
  "instance": "/users",
  "errors": {
    "email": ["The email field must be a valid email address."],
    "password": [
      "The password must be at least 8 characters long.",
      "The password must contain at least one number."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Problemas são inevitáveis em qualquer sistema, mas retornar erros bem estruturados pode facilitar a vida de quem está consumindo seu serviço mais fácil!

Referências

  1. Zuplo. The Power of Problem Details. Disponível em: https://zuplo.com/blog/2023/04/11/the-power-of-problem-details.

  2. Swagger. Problem Details RFC9457: Doing API Errors Well. Disponível em: https://swagger.io/blog/problem-details-rfc9457-doing-api-errors-well/#references.

  3. IETF. RFC 7807 - Problem Details for HTTP APIs. Disponível em: https://datatracker.ietf.org/doc/html/rfc7807.

Top comments (0)