Tratamento erros API: 9 padrões para APIs REST

9 Padrões de Tratamento de Erros em API que Toda Equipe Deveria Adotar

Erros em API são inevitáveis. O que diferencia uma boa integração de uma dor de cabeça constante é como você os comunica. Tratamento erros API não é sobre evitar falhas, é sobre torná-las previsíveis e acionáveis para quem consome seu serviço. Abaixo, os nove padrões que estruturam essa comunicação.

1. Use códigos HTTP com precisão cirúrgica

Cada código tem um significado. 400 é requisição inválida, 401 é não autenticado, 403 é proibido, 404 é não encontrado. Usar 400 para tudo é preguiça que custa horas de debug alheio. Se o recurso não existe, responda 404. Se a validação falhou, 422 é mais preciso que 400.

2. Estruture o corpo do erro de forma consistente

Defina um schema único para toda resposta de erro. Um formato comum inclui code, message e details. Quando cada endpoint devolve um JSON diferente, o cliente precisa de lógica condicional para cada caso. Consistência é o que permite criar um handler genérico no front-end.

3. Inclua um identificador de correlação

Quando algo der errado, o suporte precisa rastrear o que aconteceu. Um campo requestId ou traceId no corpo do erro permite que o usuário reporte um problema específico e sua equipe encontre os logs exatos daquela requisição, sem adivinhar.

4. Mensagens de erro que ensinam, não que acusam

"Erro interno" não ajuda ninguém. "O campo email é obrigatório" orienta. Mensagens devem dizer o que aconteceu, por que aconteceu e, quando possível, como resolver. Evite expor detalhes internos de stack trace, mas seja generoso em contexto útil para o cliente.

5. Documente cada código de erro possível

Se sua API pode retornar 30 códigos de erro diferentes, eles precisam estar na documentação. Um portal com cada código, seu significado e um exemplo de resposta reduz drasticamente o volume de tickets de suporte. Quem consome sua API deveria conseguir diagnosticar sem falar com você.

6. Separe erros de validação de erros de negócio

Erro de validação significa que o dado enviado não passa nas regras de formato. Erro de negócio significa que a operação não é permitida no estado atual. Misturar os dois confunde o cliente. Use 422 para validação e 409 para conflitos de estado, por exemplo.

7. Nunca retorne HTML em uma API JSON

Se sua API promete JSON, todo erro deve ser JSON. Retornar uma página HTML de erro do servidor quebra parsers e gera falhas silenciosas no cliente. Configure sua aplicação para que até erros não tratados caiam em um formato JSON padrão.

8. Inclua links para resolver o erro quando fizer sentido

Padrões como RFC 7807 (Problem Details) sugerem uma URI que aponta para a documentação daquele erro específico. Um campo type com link para a explicação detalhada transforma uma mensagem curta em um recurso educacional. Cliente que entende, conserta sozinho.

9. Registre erros no servidor com o mesmo rigor que responde

O tratamento de erros não termina na resposta HTTP. Cada erro precisa ser logado com contexto suficiente: endpoint, parâmetros, usuário e stack trace. Sem logs bons, você cega sua equipe para problemas que só aparecem em produção.

Qual padrão adotar primeiro?

Se você está começando, foque nos itens 1 e 2: códigos HTTP corretos e estrutura consistente. Eles criam a fundação para todos os outros. Depois, adicione o identificador de correlação (item 3) e a documentação (item 5). O resto evolui naturalmente conforme sua API amadurece.

FAQ

O que é tratamento de erros em API?

É o conjunto de práticas para responder a falhas de forma padronizada e informativa. Inclui escolher o código HTTP correto, estruturar o corpo da resposta com mensagens claras e registrar o erro no servidor para diagnóstico futuro.

Qual a diferença entre 400 e 422?

400 indica que a requisição é malformada, como JSON inválido. 422 indica que a sintaxe está correta, mas a semântica falhou, como um campo obrigatório ausente ou um formato de email inválido. Usar 422 para validação de negócio é mais preciso.

Devo expor stack trace em erros de API?

Não. Stack trace revela detalhes internos do servidor, como caminhos de arquivos e versões de bibliotecas, que podem ser explorados por atacantes. Registre o stack trace nos logs do servidor, mas retorne apenas uma mensagem genérica e um identificador de correlação.

Como padronizar erros em uma API legada?

Comece criando um middleware que intercepte todas as respostas de erro e as transforme no novo formato padrão. Depois, migre gradualmente cada endpoint para usar códigos HTTP mais precisos. A consistência do formato já resolve a maioria dos problemas de integração.

O que é RFC 7807?

É uma especificação do IETF que define um formato padrão para erros HTTP, chamado Problem Details. Ela sugere campos como type, title, status e detail, permitindo que clientes entendam erros de diferentes APIs sem lógica customizada para cada uma.