Como você faz o tratamento de erros de integração da sua empresa? Eu aposto que não deu a devida atenção para este assunto!
Há quatro anos eu escrevi um post sobre Estratégia de Tratamento de Erros, porém, como os demais posts sobre SOA, parece que este assunto não fica desatualizado. Naquela ocasião, comentei que esse assunto era negligenciado.
Você precisa para considerar o tratamento de erros do serviço na estimativa da construção! Caso ele não trate, considerar isso na configuração da API!
Mas isso não é óbvio?! Infelizmente não! Lembro de ter lido ou ouvi em algum lugar que o óbvio só é óbvio quando alguém o aponta! Pesquisando um pouco achei esta frase:
O óbvio é aquilo que nunca é visto até que alguém o manifeste com simplicidade. – Khalil Gibran
Como tratar erros?
Voltando ao tratamento de erros, uma vez estabelecido que eles precisam ser tratados, como fazer?
A resposta padrão é, como sempre, depende! Depende da arquitetura de referência de sua empresa. Para deixar mais palpável, vou propor um modelo que acho válido:
Note que independente do estilo arquitetural da integração, o tratamento de erros de integração, assim como a modelagem, deve ser homogêneo. Desta forma o consumidor se sentirá mais confortável ao consumir diversos serviços e/ou APIs, pois todos eles apresentarão um comportamento parecido.
Logo de cara, vamos nos deparar com diversos sistemas, cada um com seu estilo de tratamento de erros:
- Um expõe detalhes de implementação, muitas vezes de forma demasiada, compromentendo a segurança do sistema;
- Outro ‘engole’ as exceções, dificultando muito a resolução de problemas (troubleshooting);
- Um retorna erro ao não encontrar dados;
- Outro retorna uma ‘lista vazia’;
- Um terceiro retorna null;
- Um tem códigos de erros padronizados;
- Outro não trata corretamente os erros, lançando runtime exceptions genéricas da plataforma de desenvolvimento (quem nunca ‘tomou um’ nullpointer exception e não sabe por onde começar?
- E esta lista não teria fim ….
Como dito, independente da abordagem escolhida, o mais importante é a padronização entre os serviços, eles tem que ter um tratamento de erros consistente. Quando for definir este padrão, leve em conta os seguintes ítens:
- Código de erro – o ideal seria ter um catálogo documentado dos principais erros;
- Descrição – um descritivo resumido do erro;
- Sistema origem – sistema que lançou o erro;
- Detalhes ou instruções – mais detalhes sobre o erro e/ou como resolve-lo;
- Stack trace – opcionalmente retornar a pilha de exceções geradas;
Web Services Tradicionais
Em SOAP, sugere-se o uso de SOAP-Faults, por serem uma estrutura padronizada. Desta forma uma sugestão seria:
soap:Server
Erro desconhecido XPTO
SistemaABC.WebserviceCDE.operacaoFGH
123
Erro desconhecido XPTO
Para evitar este erro ...
....
Serviços e API’s REST
Quando usamos o Estilo Arquitetural REST, é possível reaproveitar a maioria das definições acima com alguns detalhes:
HTTP Status Codes
É preciso levar em considearação os status codes retornados, não faz mais sentido retornar sempre HTTP Status Code 200 - Ok (você não quer escrever um Serviço ou API RESTbut, quer?) caso um erro tenha ocorrido. Tenha sempre em mente a regra de ouro, que é a padronização! , todas as API’s devem retornar o mesmo conjunto de HTTP Status Codes, por exemplo:
| Status Code | Descrição |
|---|---|
| 200 | Sucesso |
| 400 | Parâmetros Inválidos |
| 401 | Credencial Inválida (problema de usuário e senha) |
| 403 | Credencial não possui permissão para o recurso |
| 404 | Não encontrado |
| 405 | Método não implementado |
| 500 | Erro invesperado |
Outro detalhe é que os HTTP Status Codes podem e devem variar de acordo com o Método utilizado! Para o POST é comum retornar o código 201 - Created por exemplo.
Payload
Aqui viriam o os detalhes presentes no elemento minhaFault do exemplo acima, porém, como dito no Estratégia de Tratamento de Erros, para API’s é muito importante implementar o Exception Shielding. Desta forma, elementos como faultActor e trace devem ser suprimidos e instrucoes podem/devem ser repensadas.
Além disso, é recomendado utilizar um link para uma página de documentação específica (help), desta forma o elemento instrucoes pode ser suprimido:
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8{ "codigoErro":"API-123", "descricao":"Erro desconhecido XPTO", "maisInformacoes": "https://felipefirmo.com.br/codigos_erro.html" }
Conclusão
Sei que na maioria das vezes não temos autonomia para alterar a arquitetura, mas sempre tem espaço para melhorar, se não pode mudar, pode influenciar.
Em último caso, tenho certeza que mesmo não podendo atuar na estrutura, podem melhorar os valores retornados. Isso já ajuda muito, é o mais importante. A estrutura é apenas um guia.
Espero que tenha conseguido fazer você refletir sobre tratamento de erros de integração, e que tenha compreendido o modelo que sugeri.
Mas se esse não é seu caso, ou o texto está muito complicado, me mande uma mensagem no Instagram. Estou sempre tirando dúvidas de integração nos stories.
Se não tem tempo para isso e gostaria compreender melhor esse universo de integração online, clique aqui que logo vou fazer uma oferta exclusiva!
