Validacao e erros em API REST: boas praticas para respostas previsiveis

Uma API REST pode ter endpoints corretos e ainda assim gerar retrabalho se as respostas de erro forem confusas. Quando qualquer problema vira 500, quando validacao retorna texto solto, quando campos invalidos nao aparecem claramente ou quando o frontend precisa adivinhar o motivo da falha, o contrato da API fica fragil.

Validacao e erro nao sao detalhes finais. Eles fazem parte da experiencia de integracao. Uma boa resposta de erro ajuda cliente, frontend, suporte e equipe tecnica a entender o que aconteceu sem expor detalhes internos.

Este guia organiza boas praticas para pequenas empresas e times que mantem APIs REST em Spring Boot ou stacks semelhantes.

1. Erro tambem faz parte do contrato

O contrato de uma API nao e apenas a resposta de sucesso. Consumidores tambem precisam saber o que acontece quando um campo esta ausente, quando o usuario nao tem permissao, quando um recurso nao existe ou quando uma regra de negocio impede a operacao.

Documente pelo menos:

• status HTTP esperados;
• formato do corpo de erro;
• campos obrigatorios;
• codigos internos de erro, quando existirem;
• exemplos de validacao;
• exemplos de regra de negocio;
• respostas para falhas inesperadas.

O hub de APIs REST e integracoes organiza outros conteudos sobre contratos, DTOs, logs e evolucao segura.

2. Use status HTTP com criterio

Status HTTP ajuda o consumidor a entender a categoria da falha. Usar sempre 200 ou sempre 500 deixa a integracao opaca.

Um mapa simples:

• 400 Bad Request: payload invalido, campo ausente ou formato incorreto;
• 401 Unauthorized: autenticacao ausente ou invalida;
• 403 Forbidden: usuario autenticado sem permissao;
• 404 Not Found: recurso nao encontrado;
• 409 Conflict: conflito de estado ou regra de negocio;
• 422 Unprocessable Entity: dados compreendidos, mas semanticamente invalidos, quando a API adota esse padrao;
• 500 Internal Server Error: falha inesperada que precisa de investigacao tecnica.

O importante e manter consistencia. Se a API trata a mesma situacao de formas diferentes em endpoints diferentes, o cliente da integracao sofre.

3. Padronize o corpo de erro

Uma resposta de erro deve ser legivel para humanos e previsivel para sistemas. Um formato comum evita que cada endpoint invente sua propria estrutura.

Campos uteis:

• timestamp ou horario do erro;
• status HTTP;
• error ou titulo curto;
• message segura para o consumidor;
• path da rota;
• requestId para suporte;
• code interno estavel;
• fieldErrors para erros por campo.

Algumas APIs adotam o formato Problem Details. Outras usam um envelope proprio. O formato importa menos do que a consistencia e a documentacao.

4. Trate validacao de campo como caso comum

Campo obrigatorio ausente, e-mail invalido, tamanho excedido, valor fora do dominio e data malformada nao deveriam gerar erro generico. Sao erros esperados.

Em Spring Boot, Bean Validation ajuda a declarar regras em DTOs de entrada. Mas a resposta ao consumidor ainda precisa ser padronizada.

Exemplo de informacao util:

• campo: email;
• codigo: email.invalid;
• mensagem: Informe um e-mail valido.;
• valor rejeitado: opcional e apenas quando nao for sensivel;
• regra: opcional, como tamanho minimo ou formato esperado.

Evite devolver nomes internos de classes, stack trace ou mensagens tecnicas que so fazem sentido para quem desenvolve.

5. Separe validacao tecnica de regra de negocio

Nem todo erro de entrada e igual. Validacao tecnica verifica formato e obrigatoriedade. Regra de negocio verifica se a operacao faz sentido para a empresa.

Exemplos de validacao tecnica:

• campo obrigatorio vazio;
• data em formato invalido;
• numero negativo onde nao pode;
• e-mail sem formato valido.

Exemplos de regra de negocio:

• pedido ja foi finalizado;
• cliente esta bloqueado;
• periodo financeiro esta fechado;
• usuario nao pode alterar recurso de outra empresa;
• lead duplicado precisa ser tratado de forma especifica.

Separar essas categorias melhora status HTTP, mensagem, teste e atendimento.

6. Nao exponha detalhe interno em erro 500

Falha inesperada precisa aparecer nos logs, nao no corpo da resposta. O consumidor deve receber uma mensagem segura e um identificador para suporte.

Resposta segura pode dizer:

• ocorreu uma falha inesperada;
• o time tecnico pode investigar com o request ID;
• o cliente pode tentar novamente quando fizer sentido;
• nenhum detalhe sensivel foi exposto.

O artigo Logs e correlacao de requisicao em Spring Boot mostra como usar request ID, MDC e logs estruturados para investigar sem vazar stack trace ao usuario.

7. Garanta que o frontend saiba o que fazer

Um erro bem modelado ajuda o frontend a mostrar mensagem correta. Se a API devolve apenas "erro", a interface precisa improvisar.

O frontend pode usar:

• erros por campo para destacar inputs;
• codigo interno para mensagem traduzida;
• status 401 para redirecionar autenticacao;
• status 403 para mostrar falta de permissao;
• status 409 para explicar conflito;
• request ID para orientar suporte.

Isso reduz chamados repetidos e evita que o usuario veja mensagens tecnicas demais.

8. Registre logs sem duplicar ruido

Nem todo erro precisa virar log de erro com stack trace. Validacao de campo normalmente e comportamento esperado. Erro 500, falha de integracao, banco indisponivel e excecao inesperada merecem mais atencao.

Um padrao saudavel:

• validacoes comuns em nivel baixo ou sem stack;
• regras de negocio registradas quando ajudarem suporte;
• falhas inesperadas com stack trace e request ID;
• chamadas externas com tempo e resultado;
• nenhum token, senha ou payload sensivel em log.

A pagina de evidencias tecnicas ajuda a decidir que dados guardar para investigacao.

9. Documente exemplos na API

OpenAPI ou Swagger ficam muito mais uteis quando incluem exemplos de erro. Nao basta documentar apenas 200.

Inclua exemplos de:

• 400 com erro de campo;
• 401 sem autenticacao;
• 403 sem permissao;
• 404 para recurso ausente;
• 409 para conflito de regra;
• 500 com mensagem segura e request ID.

O artigo Checklist de API Spring Boot em producao complementa essa revisao com contratos, seguranca, banco, logs, deploy e rollback.

10. Teste erros como testa sucesso

Fluxos felizes costumam receber mais atencao, mas erros mal tratados geram boa parte do suporte. Teste respostas negativas.

Casos importantes:

• payload vazio;
• campo obrigatorio ausente;
• valor invalido;
• recurso inexistente;
• usuario sem permissao;
• conflito de regra de negocio;
• falha simulada de dependencia externa;
• erro inesperado convertido em resposta segura.

Esses testes protegem integracoes e reduzem regressao quando a API evolui.

Checklist para padronizar erros REST

1. Defina um formato unico de erro.
2. Use status HTTP com criterio e consistencia.
3. Liste campos invalidos em erros de validacao.
4. Separe validacao tecnica de regra de negocio.
5. Inclua request ID em falhas que exigem suporte.
6. Nao exponha stack trace ao consumidor.
7. Documente exemplos de erro no OpenAPI.
8. Teste respostas negativas.
9. Registre logs proporcionais ao tipo de erro.
10. Revise se o frontend consegue agir com a resposta.

APIs boas nao sao avaliadas apenas quando tudo funciona. Elas tambem precisam falhar de forma compreensivel, segura e previsivel. Esse cuidado reduz retrabalho, melhora suporte e torna integracoes mais confiaveis.

Se a API ja existe e cresceu sem padrao, o caminho nao precisa ser reescrever tudo. Comece por padronizar erro, validar contratos e criar evidencias. Depois, evolua endpoint por endpoint com criterio.