Tratamento de erros em integrações: retentativas e idempotência

Integrações falham. Serviços ficam indisponíveis por alguns minutos, a rede oscila, um dado chega em formato inesperado, um limite de requisições é atingido. A questão não é se as falhas vão acontecer, e sim como a integração se comporta quando elas acontecem.

Integrações bem desenhadas tratam erros de forma previsível: recuperam-se sozinhas quando possível e avisam alguém quando não é.

Tipos de falha

Temporárias

O serviço estava indisponível, a conexão caiu, o limite de requisições foi atingido. Tentando novamente após algum tempo, a operação provavelmente terá sucesso.

Permanentes

O dado é inválido, um campo obrigatório está faltando, o registro referenciado não existe. Repetir a operação não vai resolver; é preciso corrigir algo.

Distinguir os dois tipos é o primeiro passo do tratamento.

Retentativas com espera progressiva

Para falhas temporárias, a integração deve tentar novamente, mas não de forma imediata e repetida. A prática recomendada é aumentar o intervalo entre as tentativas: alguns segundos, depois mais, depois mais ainda. Isso dá tempo para o serviço se recuperar e evita sobrecarregá-lo.

Defina também um limite de tentativas. Depois dele, o item vai para uma fila de análise.

Idempotência

Uma operação é idempotente quando executá-la várias vezes produz o mesmo resultado que executá-la uma vez. Isso é essencial em integrações, porque retentativas podem fazer a mesma operação chegar duas vezes ao destino.

Exemplos de técnicas:

• Enviar um identificador único por operação, que o destino usa para reconhecer repetições.
• Verificar se o registro já existe antes de criá-lo.
• Preferir operações de "criar ou atualizar" em vez de "criar" sempre que fizer sentido.

Sem idempotência, uma retentativa pode gerar pedidos ou pagamentos duplicados.

Fila de reprocessamento

Itens que falharam de forma permanente, ou que esgotaram as tentativas, devem ir para uma fila de análise, com:

• O dado original.
• A mensagem de erro.
• A data e o número de tentativas.

Depois da correção, deve ser possível reprocessar o item sem trabalho manual excessivo.

Não pare tudo por um item

Em integrações que processam lotes, um registro com problema não deve impedir o processamento dos demais. Isole o erro, registre-o e siga com o restante.

Alertas úteis

• Avise quando a fila de erros crescer além do normal.
• Avise quando a integração parar de processar por completo.
• Inclua no alerta informações para diagnóstico.
• Evite alertas para cada falha temporária que foi resolvida com retentativa.

Registros para investigação

Registre as chamadas, as respostas e os erros, com identificadores que permitam rastrear um item do início ao fim. Tome cuidado para não registrar dados sensíveis ou credenciais.

Teste os cenários de falha

Simule indisponibilidade, respostas lentas, dados inválidos e repetições. Integrações costumam ser testadas apenas no cenário de sucesso, e é justamente nas falhas que os problemas aparecem.

A CavData desenvolve integrações com tratamento de erros, monitoramento e reprocessamento. Conheça o serviço de desenvolvimento de software sob medida.