Erros e retentativas no n8n: fluxos de IA que não quebram

Erros e retentativas no n8n: fluxos de IA que não quebram

Para tratar erros e retentativas no n8n, ative o retry apenas nos nós seguros de repetir (como a chamada ao LLM), com limite de tentativas e espera entre elas. Depois, direcione as falhas finais para um fluxo de erro que avise uma pessoa e entregue ao cliente uma resposta de contingência. O ponto central é separar gerar a resposta de enviar a resposta: só o primeiro passo pode ser repetido sem risco de duplicar mensagem.

Principais pontos

• Falha de API de LLM é rotina, não exceção: limite de uso, lentidão e indisponibilidade passada acontecem, e o fluxo precisa prever isso.
• Retry sem limite e sem critério causa dois problemas: mensagem duplicada para o cliente e gasto descontrolado.
• Repita só passos que podem ser refeitos sem efeito colateral. O envio ao cliente deve ter uma chave de controle que impeça segundo envio.
• Toda falha final precisa de dois destinos: um alerta para a equipe e uma saída para o cliente (resposta de contingência ou transferência para humano).
• Teste as falhas de propósito antes de ir para produção, porque o caminho de erro quase nunca é exercitado por acidente.

Por que falhas de LLM geram duplicidade ou silêncio?

Um fluxo de IA no n8n costuma ter uma sequência simples: chega uma mensagem (por webhook, por exemplo), o fluxo monta o contexto, chama o modelo, valida a resposta e envia ao cliente. Cada etapa depende de um serviço externo, e qualquer um pode falhar.

O silêncio acontece quando o nó do LLM dá erro e o fluxo simplesmente para. Na configuração padrão, o n8n interrompe a execução, e o cliente fica sem resposta. Ninguém da equipe vê, porque a falha só aparece na lista de execuções, que ninguém abre o dia todo.

A duplicidade tem duas origens comuns. A primeira é aplicar retry em um nó que já teve efeito colateral, por exemplo repetir um bloco inteiro que inclui o envio da mensagem. A segunda é o remetente reenviar o webhook porque o fluxo demorou a responder, e o n8n processar o mesmo evento duas vezes. A documentação de webhooks da Stripe descreve esse comportamento de entrega repetida em um provedor real, e a lógica vale para qualquer origem de eventos: assuma que o mesmo evento pode chegar mais de uma vez.

O erro de projeto por trás dos dois problemas é o mesmo: tratar o fluxo como uma linha reta que sempre termina bem, em vez de um processo com estados (recebido, gerado, enviado, falhou).

Quais erros merecem nova tentativa e quais não?

Antes de ligar qualquer retry, classifique os erros. Repetir um erro que não é temporário só atrasa o problema e gasta chamadas.

• Limite de uso excedido (resposta de taxa): vale tentar de novo, com espera maior entre as tentativas.
• Timeout ou erro de servidor do provedor: vale tentar de novo, poucas vezes.
• Erro de autenticação ou permissão (chave inválida, expirada, sem saldo): não repita. É falha de configuração, e o alerta deve ir direto para quem administra o fluxo.
• Requisição malformada (campo faltando, contexto grande demais para o modelo): não repita a mesma chamada. Corrija a entrada ou reduza o contexto. Sobre esse limite, veja janela de contexto em IA.
• Resposta do modelo fora do formato esperado ou reprovada na validação: no máximo uma nova geração, e só se o seu passo de validação for confiável. Depois disso, transfira para uma pessoa.
• Falha no envio ao canal (WhatsApp, e-mail): só repita se houver chave de controle que garanta que a mensagem não saiu na tentativa anterior.

Os códigos exatos variam por provedor. Consulte a documentação da API que você usa e anote, para cada classe de erro, a decisão tomada. Esse quadro vira parte do material de entrega do fluxo.

Como configurar retentativas com limite no n8n?

No n8n, as configurações de erro ficam por nó, na aba de configurações. Os nomes podem mudar entre versões, então confirme na documentação oficial da sua versão. Em geral, você encontra três controles relevantes.

• Retry On Fail: liga a repetição automática do nó quando ele falha. Com ele aparecem o número máximo de tentativas e o tempo de espera entre elas.
• On Error: define o que acontece quando o nó falha de vez. Pode parar o fluxo, continuar ignorando o erro ou continuar usando uma saída de erro separada.
• Timeout nas chamadas HTTP: se você chama o modelo por um nó de requisição, defina um tempo máximo, para que uma chamada travada não segure o fluxo indefinidamente.

Sobre o limite de tentativas, a regra prática é manter o número baixo. Chamada de modelo custa dinheiro e tempo, e o cliente está esperando. Duas ou três tentativas costumam bastar para falhas passageiras, e o que passar disso é problema que precisa de gente.

A espera entre tentativas no retry nativo é fixa. Se o seu caso exige espera crescente (comum com limite de taxa), monte um pequeno laço: um contador, um nó de espera cujo tempo aumenta a cada volta e uma condição que sai do laço quando o contador chega ao máximo. O contador é obrigatório. Um laço sem teto é a mesma classe de problema descrita em agente de IA em loop infinito, com o agravante de gasto a cada volta.

O mais importante é a ordem: ative o retry no nó do LLM, nunca em um bloco que contenha o envio. Se o modelo for chamado duas vezes e só a segunda resposta for enviada, o cliente não percebe nada. Se o envio for chamado duas vezes, ele percebe.

Como evitar mensagem duplicada mesmo com retry?

A ferramenta para isso se chama idempotência: repetir a operação com a mesma chave produz o mesmo efeito de executar uma vez. A documentação da Stripe sobre requisições idempotentes é um bom exemplo de como um provedor formaliza a ideia. No n8n, você implementa o equivalente com uma tabela de controle.

O desenho funciona assim:

• Toda mensagem recebida traz um identificador único (o ID da mensagem do canal). Use esse valor como chave.
• No início do fluxo, consulte a tabela de controle (pode ser uma planilha, um banco ou a Data Table do próprio n8n, conforme sua versão). Se a chave já existe com estado enviado, encerre sem fazer nada.
• Se a chave não existe, grave com estado em processamento e siga.
• Depois do envio bem-sucedido, atualize o estado para enviado.
• Se o fluxo falhar no meio, o estado em processamento permanece, e o fluxo de erro sabe que aquela conversa precisa de atenção.

Um detalhe operacional: responda ao webhook de entrada rapidamente. Se o remetente espera uma confirmação e o fluxo gasta tempo chamando o LLM, ele pode reenviar o evento. Confirmar o recebimento primeiro e processar depois reduz a chance de reenvio, e a chave de controle cobre o que sobrar.

Se o canal é o WhatsApp, lembre que há regras próprias sobre quando você pode enviar mensagem. Um reenvio automático fora da janela de atendimento pode exigir template aprovado. O texto sobre mensagens ativas no WhatsApp detalha esse ponto, e o guia de integração de IA no WhatsApp da empresa cobre a arquitetura geral.

Como montar o fluxo de erro e os alertas?

O n8n permite designar um fluxo de erro: um segundo fluxo, iniciado pelo nó Error Trigger, que é acionado quando um fluxo principal falha em execução automática. Você o associa na configuração do fluxo principal, no campo de fluxo de erro. Dois cuidados: ele não dispara em execuções manuais de teste, e é preciso associar cada fluxo importante a ele, porque a ligação não é global.

O Error Trigger entrega dados como o nome do fluxo, o nó em que falhou, a mensagem de erro e o identificador da execução. Com isso, o fluxo de erro deve fazer quatro coisas.

• Avisar uma pessoa, em um canal que ela realmente olha (grupo interno, e-mail de plantão). A mensagem de alerta deve dizer qual fluxo falhou, em qual nó, e trazer o link da execução.
• Marcar a conversa como pendente na tabela de controle, para que nenhuma mensagem fique esquecida.
• Enviar ao cliente uma resposta curta de contingência, quando fizer sentido, ou acionar a transferência para atendimento humano.
• Evitar a tempestade de alertas: se o provedor do modelo cai, dezenas de execuções falham juntas. Agrupe os avisos ou limite a frequência, senão a equipe passa a ignorar o canal.

Para falhas que você quer tratar dentro do próprio fluxo, use a opção de continuar com saída de erro no nó do LLM. Essa saída leva a um ramo que decide: tentar um modelo alternativo, usar a resposta de contingência ou encaminhar para uma pessoa. O nó Stop And Error é útil para forçar uma falha deliberada quando a validação reprova a resposta, de modo que o fluxo de erro seja acionado com uma mensagem clara.

Não trate o alerta como o fim do trabalho. Registre cada falha com data, nó, classe de erro e desfecho. Esse histórico é o que permite ver padrões, e os conceitos de observabilidade da OpenTelemetry ajudam a pensar em logs, métricas e rastros sem depender de uma ferramenta específica. Para validar a saída do modelo antes de enviar, veja guardrails para agentes de IA.

Sobre privacidade: o alerta não deve carregar o texto da conversa do cliente. Envie identificadores e links para a execução, e deixe o conteúdo acessível apenas a quem tem permissão no n8n. Isso reduz a exposição de dados pessoais em canais de chat internos, o que importa para a LGPD.

Cenário ilustrativo: uma distribuidora e o limite de taxa

Cenário ilustrativo: uma distribuidora de materiais elétricos recebe pedidos de cotação pelo WhatsApp. O fluxo lê a mensagem, chama o modelo para extrair itens e quantidades, consulta o estoque e responde com uma confirmação.

Numa manhã de movimento, o provedor do modelo começa a devolver erro de limite de uso. No desenho ruim, o nó do LLM está dentro de um bloco com o envio e o retry está ligado para todo o bloco. O resultado: alguns clientes recebem a confirmação duas vezes, outros nenhuma, e a equipe descobre à tarde.

No desenho corrigido, a sequência muda. O ID da mensagem é gravado na tabela de controle antes de tudo. O retry fica só no nó do LLM, com poucas tentativas e espera maior. Se o limite persiste, o ramo de erro marca a conversa como pendente, envia ao cliente uma frase como "recebemos seu pedido e um atendente vai confirmar em breve" e avisa o grupo interno uma única vez. Quando o provedor se normaliza, a equipe reprocessa as pendentes pela tabela, sem risco de duplicar, porque o estado de cada uma está registrado.

Plano passo a passo e como aplicamos o método

Use esta sequência para revisar um fluxo existente ou construir um novo.

• Liste os nós do fluxo e marque quais têm efeito colateral (enviar mensagem, gravar no CRM, criar pedido).
• Separe o fluxo em duas partes: gerar a resposta (repetível) e entregar a resposta (controlada por chave).
• Crie a tabela de controle com a chave da mensagem, o estado e a data.
• Ligue o retry apenas nos nós sem efeito colateral, com máximo de tentativas baixo e espera entre elas. Defina timeout nas chamadas.
• Configure a saída de erro do nó do LLM e escreva a resposta de contingência, com revisão de quem conhece o atendimento.
• Crie o fluxo de erro com Error Trigger, alerta para uma pessoa, marcação de pendência e limite de frequência de avisos.
• Associe o fluxo de erro a cada fluxo principal.
• Teste de propósito: chave de API inválida, timeout forçado, resposta fora do formato, webhook enviado duas vezes. Confirme que nada duplica e que nada fica em silêncio.
• Defina quem recebe o alerta, em qual horário e o que essa pessoa faz primeiro.

O método que usamos nesses projetos segue a mesma lógica. Mapear: desenhar o processo atual e onde ele pode falhar. Limitar: fixar tentativas, tempo e ações permitidas ao fluxo. Pilotar: rodar um fluxo real com logs e um critério de sucesso combinado, incluindo falhas provocadas. Transferir: entregar a documentação dos erros conhecidos e do que fazer em cada um, para que a operação não dependa de quem montou. Esse tipo de acompanhamento contínuo é o que a Be Human cobre na operação gerenciada.

Perguntas frequentes

Quantas retentativas devo configurar no n8n para uma chamada de LLM? Poucas. Duas ou três costumam cobrir falhas passageiras, e mais do que isso aumenta o tempo de espera do cliente e o gasto sem melhorar a chance de sucesso. Se a falha persiste, o caminho certo é o fluxo de erro, não mais tentativas.

O retry do n8n pode causar mensagem duplicada? Pode, se estiver ligado em um nó que já produziu efeito, como o envio ao cliente, ou se o mesmo evento de entrada for processado duas vezes. A defesa é manter o retry no passo de geração e usar uma chave de controle, como o ID da mensagem, para impedir um segundo envio.

O fluxo de erro do n8n funciona em execuções de teste manuais? Em geral, não. Ele é acionado por execuções automáticas, como as iniciadas por webhook ou agendamento, então o teste do caminho de erro deve ser feito ativando o fluxo e provocando a falha de verdade. Confirme o comportamento na documentação da sua versão do n8n.

O que o cliente deve receber quando o modelo de IA está fora do ar? Uma resposta curta e honesta, dizendo que o pedido foi recebido e que uma pessoa vai continuar o atendimento, junto com a transferência efetiva para humano. Evite prometer prazo que você não controla, e evite repetir a mensagem a cada nova tentativa do cliente.

Fontes

• Stripe: requisições idempotentes
• Stripe: entrega e verificação de webhooks
• OpenTelemetry: conceitos de observabilidade