Agente de IA no n8n falhou no meio: como retomar a execução sem reprocessar tudo nem pagar tokens de novo

Fala aí, beleza? O cenário é este: teu workflow no n8n buscou os dados, passou uma parte deles pelo agente de IA, talvez já tenha mandado um e-mail ou gravado uma linha na planilha… e travou no meio 😛

Você não quer rodar tudo de novo, porque cada chamada ao LLM custa e algumas ações não podem acontecer duas vezes

Este post não trata da causa do erro

O objetivo é recuperar o que já rodou e executar só o pedaço que falta

A base é a documentação oficial do n8n consultada em 20/10/2026. Nessa data, as release notes marcavam a estável 2.44.4 e a beta 2.45.0. A estável é a indicada para produção, e a beta é a release mais recente

Se liga: o n8n lança uma versão minor quase toda semana, então esses números mudam rápido

Retry execution, Debug in editor ou Execute step: qual usar para retomar?

Para retomar uma execução no n8n, a documentação oferece quatro opções. A diferença entre elas está nos dados que cada uma reaproveita e no tipo de execução que ela gera

A aba Executions fica na página Overview ou dentro de um projeto

Agora, tome cuidado!

A documentação das duas opções de retry só diz que elas usam os dados da execução anterior. Ela não diz se o retry começa no nó que falhou ou no início do workflow

Então não conte com o Retry para pular o agente ou evitar tokens repetidos. Trate como se ele pudesse passar de novo por tudo

O Debug in editor está disponível no n8n Cloud e no plano Community registrado

O nó do agente estourou timeout ou limite do provedor do LLM:

Neste caso, a falha acontece no nó que chama o modelo, depois que a coleta e o tratamento dos dados já tinham dado certo

Refazer essas etapas só para chegar de novo ao agente é desperdício

Como retomar só o nó do agente?

1. Na aba Executions, abra a execução que falhou e use Debug in editor. O n8n copia os dados para o workflow atual e fixa o primeiro nó
2. Nos nós anteriores ao agente que já deram certo, fixe (pin) a saída deles
3. Abra o nó do agente e clique em Execute step

Por que isso funciona? Segundo a página de data pinning, em execução manual o n8n usa os dados fixados no lugar de executar o nó fixado e segue o fluxo normalmente

O Execute step roda o nó e os anteriores necessários para gerar a entrada dele. Com os anteriores fixados, quem roda de verdade é o agente

Para confirmar, veja se só o nó do agente processou nesta rodada. Os nós fixados devem continuar com a mesma saída da execução original

Como evitar da próxima vez?

Nas Settings do nó, ligue Retry On Fail. Com ele ligado, aparecem Max Tries e Wait Between Tries (ms)

O Wait Between Tries é o tempo de espera entre uma tentativa e outra

A documentação sobre rate limit recomenda colocar nesse campo um valor acima do limite da API. Por exemplo, uma API que aceita 1 requisição por segundo pede 1000 ms

O erro comum é colocar uma espera menor que o limite real da API e queimar todas as tentativas em sequência

Falhou depois de enviar e-mail ou gravar registro: como reexecutar sem duplicar?

Aqui o problema é mais sério

Antes da falha, já rodaram nós com efeito colateral: o e-mail saiu, a linha entrou no banco ou na planilha

Se você usar Retry execution ou Execute step sem cuidado, o fluxo pode passar de novo por esses nós. Resultado: cliente recebendo dois e-mails e registro duplicado… 😬

Como seguir só o trecho que falta?

Use a execução manual com Debug in editor e fixe também a saída dos nós de efeito colateral que já rodaram

Como os nós fixados não são executados em execução manual, o e-mail não sai de novo e a gravação não se repete. O fluxo segue só pelo trecho que ainda não rodou

Para confirmar, cheque o destino real (caixa de saída, tabela, planilha) e veja se não apareceu nada duplicado

E a tal da idempotência?

Uma ação é idempotente quando rodar duas vezes dá o mesmo resultado que rodar uma vez

Isso não é um recurso pronto do n8n. É uma decisão de desenho do workflow

Por exemplo, antes do nó que grava, consulte se o registro já existe e só grave se não existir. Se o fluxo passar de novo por ali, nada se duplica

Como evitar da próxima vez?

Nas Settings de cada nó existe a opção On Error, com três escolhas: Stop Workflow (padrão), Continue e Continue (using error output)

Com Continue (using error output), o item com erro vai para uma saída separada e o fluxo não para. Assim você trata a falha num caminho próprio

Pense também na ordem dos nós: deixe as ações com efeito colateral o mais perto possível do fim, depois das etapas que mais costumam falhar

A execução parou no meio de um lote longo de itens:

Este é o caso clássico: você mandou um monte de itens pelo agente e a execução parou no meio

O que dá para fazer com segurança é recuperar os dados pela execução salva (Debug in editor) e usar Execute step com os mesmos dados de entrada

Mas atenção: a documentação não promete que o n8n retoma do item exato onde parou. Conte com a possibilidade de o lote ser reprocessado

Se os itens que já passaram pelo agente geraram efeito colateral, volte à seção anterior antes de reexecutar

Como evitar da próxima vez?

Divida o volume em lotes. A documentação de rate limit indica este desenho:

• Loop Over Items antes do nó do agente, com o Batch Size definindo quantos itens saem a cada vez
• Um nó Wait depois do agente, ligado de volta ao Loop Over Items, para pausar entre os lotes

Segundo a documentação do Loop Over Items, ele é recomendado para dados grandes, para rodar nós várias vezes e para evitar rate limit

E ele para sozinho depois de repassar todos os itens, então não precisa de IF para encerrar o loop

O erro comum é montar um IF para sair do loop, o que só complica o fluxo 🙂

A falha aconteceu em produção e ninguém viu:

O workflow ativo falhou em silêncio e, quando alguém percebe, não há execução salva para recuperar

Normalmente a causa está em duas coisas: a configuração de salvamento de execuções e a falta de um alerta

Como garantir que a execução fique salva?

Nas Workflow Settings existem três opções:

• Save failed production executions: salva as execuções de produção que falharam, em workflows ativos
• Save successful production executions: salva as que deram certo
• Save manual executions: salva as execuções iniciadas por você no editor

Para retomar, a primeira é a mais importante. Sem execução salva, não há o que carregar no Debug in editor

As outras duas ajudam quando você quer comparar com uma execução que deu certo (Copy to editor) ou guardar o que rodou no editor

Como ser avisado quando falhar?

Com um error workflow, que é um workflow que roda quando outra execução falha. O passo a passo está na página sobre tratamento de erros

1. Crie um workflow que comece com o nó Error Trigger e salve
2. No workflow que você quer monitorar, abra Options > Settings
3. No campo Error workflow, escolha o workflow que você criou

Depois do Error Trigger, você liga o aviso que preferir

Caso o erro venha do nó de trigger do workflow principal, o error workflow recebe dados diferentes. Lembre disso ao montar a mensagem de alerta

Checklist para preparar workflows longos com agente de IA para retomada:

1. Ative o salvamento de execuções com falha. Nas Workflow Settings, ligue Save failed production executions e, se fizer sentido, Save successful production executions. Como verificar: depois de uma falha, a execução deve aparecer na aba Executions. Erro comum: só descobrir que não estava salvando quando precisa recuperar
2. Configure o error workflow. Crie o workflow com Error Trigger e selecione em Options > Settings > Error workflow. Como verificar: o workflow aparece selecionado no campo Error workflow. Erro comum: esquecer que falhas no nó de trigger mandam dados diferentes
3. Ligue Retry On Fail nos nós que chamam o LLM ou APIs. Ajuste Max Tries e Wait Between Tries (ms) acima do limite da API. Como verificar: os dois campos aparecem nas Settings do nó. Erro comum: espera curta demais para o limite do provedor
4. Divida volumes grandes. Use Loop Over Items com Batch Size e um Wait ligado de volta ao loop. Erro comum: colocar um IF para encerrar, que não é necessário
5. Defina On Error em cada nó. Escolha entre Stop Workflow, Continue e Continue (using error output) conforme o que aquele nó pode tolerar. Erro comum: deixar tudo no padrão sem pensar em qual nó deveria desviar a falha
6. Isole e proteja os nós com efeito colateral. Coloque e-mail e gravações depois das etapas instáveis e confira se o registro já existe antes de gravar. Erro comum: reexecutar e duplicar envio ou registro
7. Saiba onde o pinned data funciona. Dados fixados só valem em execução manual. Erro comum: esperar que o dado fixado seja respeitado numa execução de produção (ele é ignorado)

Quer ver um agente de IA no n8n funcionando?

No canal do Hora de Codar tem um conteúdo sobre como deixar um agente de IA no n8n mais inteligente, bora ver? 😀

Próximo passo: revise um workflow antes da próxima falha

Abre hoje o workflow de agente mais longo que tu tem rodando

Confere duas coisas: se Save failed production executions está ligado e se tem um error workflow selecionado nas Settings

São poucos minutos de configuração, e é isso que garante que, na próxima falha, você vai ter o que recuperar

O princípio é o mesmo de retomar um agente que parou fora do n8n: aproveitar o que já foi feito e continuar do ponto em que parou, sem começar do zero

E como o n8n muda quase toda semana, vale dar uma olhada nas release notes antes de mexer em produção, porque nomes de opções e menus podem mudar

Até o próximo post! =)

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.