Erros 502 ou 504 na API: como tratar sem interromper sua operação

Imagine o seguinte cenário: sua aplicação envia uma nota para a API e, em vez da resposta esperada, recebe um retorno 502 ou 504.

A primeira reação pode ser pensar: “A nota não foi enviada?” ou “Preciso enviar novamente agora?”.

Mas calma. Nem sempre um retorno 502 ou 504 significa que o documento não foi recebido ou que o processamento falhou.

Em integrações por API, esses retornos podem acontecer de forma pontual por diferentes motivos, como oscilação momentânea de rede, tempo de resposta entre serviços, comunicação com gateway, balanceadores, filas de processamento ou alguma dependência temporariamente indisponível.

Por isso, mais importante do que tentar eliminar totalmente esse tipo de retorno, é garantir que sua aplicação saiba o que fazer quando ele acontecer.

O que são os retornos 502 e 504?

De forma simples:

• 502 Bad Gateway: acontece quando uma camada intermediária da comunicação recebe uma resposta inesperada de outro serviço.
• 504 Gateway Timeout:  acontece quando uma camada intermediária aguardou uma resposta, mas o tempo limite foi atingido antes da conclusão. 

Na prática, esses retornos indicam que houve uma falha transitória na comunicação. Eles não significam, automaticamente, que o documento não foi recebido pela API.

E é aqui que entra um ponto muito importante: reenviar imediatamente o mesmo documento pode não ser o melhor caminho.

Por que não devo reenviar imediatamente?

Porque existe a possibilidade de a API ter recebido a requisição original, mesmo que a resposta final não tenha chegado corretamente até a sua aplicação.

Se sua aplicação simplesmente reenviar o documento sem consultar antes, pode haver risco de duplicidade ou de perda de controle sobre o status real da emissão.

Por isso, a recomendação é: antes de reenviar, consulte.

E para consultar com segurança, o melhor caminho é utilizar o idIntegracao.

O papel do idIntegracao nesse fluxo

O idIntegracao é o identificador único enviado pela sua aplicação para representar o documento.

Pense nele como o “código de controle” da nota dentro da integração. Ele permite que a sua aplicação e a TecnoSpeed falem sobre o mesmo documento, mesmo que tenha ocorrido timeout, perda de conexão ou retorno transitório.

Com o idIntegracao, você consegue consultar a nota e entender se ela foi registrada, se está em processamento, se foi autorizada, rejeitada ou se realmente não foi localizada.

Por isso, a regra de ouro é:

Cada documento deve ter um idIntegracao único, e esse identificador deve ser armazenado pela sua aplicação.

Recebi 502 ou 504. E agora?

Ao receber um retorno 502 ou 504, siga este fluxo:

• Registre o retorno recebido.
• Aguarde alguns segundos antes de uma nova ação.
• Consulte o documento pelo idIntegracao enviado na requisição original.
• Se o documento for localizado, siga o fluxo conforme o status retornado.
• Se o documento estiver autorizado, rejeitado ou em processamento, não envie novamente.
• Se o documento não for localizado após a consulta, avalie uma nova tentativa de envio.
• Evite várias tentativas seguidas sem intervalo.

Esse comportamento ajuda sua aplicação a continuar operando com segurança, mesmo diante de uma oscilação pontual.

Vamos ver um exemplo?

1. Sua aplicação envia uma nota com o idIntegracao 12345 e recebe um retorno 502.
2. Nesse momento, o ideal não é reenviar a nota imediatamente.
3. O melhor fluxo é consultar a nota usando o mesmo idIntegracao 12345.
4. Se a consulta retornar que a nota está em processamento, sua aplicação deve aguardar o fluxo seguir.
5. Se retornar que a nota foi autorizada, basta atualizar o status na sua aplicação.
6. Se retornar que a nota foi rejeitada, siga o tratamento da rejeição.
7. Se a nota não for localizada, aí sim pode ser avaliada uma nova tentativa de envio, respeitando uma política de retentativa controlada.

Perceba que, com esse fluxo, sua aplicação não fica parada e também não assume que tudo falhou antes de confirmar o que aconteceu.

Boas práticas para evitar impacto na operação

Para deixar sua integração mais segura e preparada para situações transitórias, recomendamos:

• Use sempre o idIntegracao no envio dos documentos.
• Garanta que cada documento tenha um idIntegracao único.
• Armazene esse identificador na sua aplicação.
• Consulte o documento pelo idIntegracao antes de reenviar.
• Implemente retentativas com pequenos intervalos.
• Evite várias tentativas consecutivas sem pausa.
• Monitore a quantidade de erros em relação ao total de requisições.
• Mantenha logs com data, hora, rota, retorno recebido e idIntegracao.

Quando acionar o suporte?

Retornos 502 e 504 pontuais podem acontecer em integrações HTTP e não indicam, sozinhos, uma indisponibilidade da API.

Mas o suporte deve ser acionado quando houver:

• alta recorrência;
• concentração em uma rota específica;
• aumento relevante no percentual de falhas;
• impacto operacional persistente;
• erros concentrados em horários, documentos ou empresas específicas.

Para agilizar a análise, envie sempre que possível:

• período analisado;
• rota utilizada;
• quantidade total de requisições no período;
• quantidade de retornos 502 ou 504;
• percentual de erro identificado;
• exemplos de idIntegracao afetados;
• horários aproximados das ocorrências;
• evidências das consultas feitas após o erro;
• evidências das retentativas realizadas.

Documentações de apoio

Para apoiar a implementação desse fluxo, recomendamos a leitura dos artigos abaixo:

• Entendendo o campo identificador único - idIntegracao: Este artigo explica o que é o idIntegracao, sua importância como identificador único do documento e como ele ajuda na rastreabilidade e gestão das emissões.
• Consultar resumo da nota por id integração: Este artigo apresenta como realizar a consulta resumida de um documento utilizando o idIntegracao no PlugNotas, permitindo verificar a situação do documento após o envio. No exemplo, é citado um NFCom, mas a rota é aplicável a todos os tipos de documentos. Para consultar outro tipo de documento, basta substituir o nome do documento na requisição.