Tratar erros no n8n: Error Trigger e alertas no fluxo

Aprenda a tratar erros no n8n com o Error Trigger, o Stop and Error, o On Error e o Retry On Fail, e monte um alerta por e-mail para saber quando um fluxo falhar.

Por Redação Eleven Host · @robson.direitodigital · 29 de outubro de 2026 · 8 min de leitura

Para tratar erros no n8n, crie um fluxo separado que começa pelo nó Error Trigger e escolha esse fluxo no campo Error workflow, nas configurações do fluxo vigiado. Em cada nó, use as opções On Error e Retry On Fail.

Este guia mostra o passo a passo, quais dados o Error Trigger recebe, como forçar uma falha com o Stop and Error e como montar um alerta por e-mail. A base é a documentação do n8n sobre tratamento de erros, na versão consultada em 29/10/2026; a tela pode mudar nas versões seguintes.

Por que tratar erros no n8n

Um fluxo agendado ou acionado por webhook roda sem ninguém olhando. Se uma API muda a resposta, uma credencial expira ou o servidor de destino fica fora do ar, o fluxo falha em silêncio e você só descobre quando alguém reclama. Tratar os erros significa decidir de antemão o que acontece nesses casos: avisar você, tentar de novo ou seguir por outro caminho.

O n8n oferece quatro ferramentas para isso, que este guia explica uma a uma:

• o fluxo de erro com o Error Trigger, que roda quando outro fluxo falha;
• o nó Stop and Error, que provoca uma falha de propósito;
• a opção On Error de cada nó;
• a opção Retry On Fail de cada nó.

Criar um fluxo de erro com o Error Trigger

A documentação do n8n define o fluxo de erro como um fluxo à parte que roda quando outro fluxo falha, e ele precisa começar pelo nó Error Trigger. Quando um fluxo ligado a ele falha, o nó recebe os detalhes da falha e dispara o restante do fluxo de erro.

O passo a passo:

1. Crie um fluxo novo e coloque o Error Trigger como primeiro nó. Um nome como "Error Handler" ajuda a achá-lo depois.
2. Depois do Error Trigger, monte o aviso que você quer receber. Pode ser um e-mail, uma mensagem num aplicativo de chat ou uma chamada a outro sistema.
3. Salve o fluxo. A documentação diz que não é preciso publicar ou ativar o fluxo que contém o Error Trigger.

Um detalhe da documentação: um fluxo que contém o Error Trigger usa a si mesmo como fluxo de erro por padrão.

Quais dados o Error Trigger recebe

Segundo o exemplo da documentação, os dados chegam em dois grupos, execution e workflow:

• execution.id e execution.url: o identificador e o link da execução que falhou. A documentação avisa que os dois exigem que a execução esteja salva no banco de dados.
• execution.error.message: a mensagem do erro.
• execution.error.stack: o rastro técnico do erro.
• execution.lastNodeExecuted: o último nó executado, ou seja, onde falhou.
• execution.mode: como a execução começou.
• execution.retryOf: aparece só quando a execução é uma nova tentativa de outra que falhou.
• workflow.id e workflow.name: o identificador e o nome do fluxo.

Se quem falhou foi o próprio gatilho do fluxo principal, vem menos informação em execution e aparece um objeto trigger, com o erro do gatilho (nome, causa, horário, mensagem e nó) e o modo.

Escolher o fluxo de erro nas configurações

Criar o fluxo de erro não é o bastante: é preciso dizer a cada fluxo vigiado qual fluxo de erro usar. Segundo a documentação:

1. Abra o fluxo que você quer vigiar.
2. Clique em Options e depois em Settings.
3. No campo Error workflow, selecione o fluxo de erro que você criou.
4. Clique em Save.

Repita para cada fluxo que precisa de aviso.

Na prática, isso muda a forma de testar: deixe o fluxo vigiado ativo com um gatilho automático e provoque uma falha controlada, como a que o nó Stop and Error faz na próxima seção. Para conhecer o gatilho de agenda, veja o guia Agendar fluxo no n8n: como usar o Schedule Trigger.

Quer pôr seus fluxos para rodar? O n8n Essencial sai a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Ver planos de n8n

Forçar uma falha com o Stop and Error

Nem toda situação errada gera um erro. Uma API pode responder com um conteúdo inválido e, mesmo assim, o n8n considerar a chamada bem-sucedida. O nó Stop and Error serve para fazer a execução falhar em certas condições e enviar informação de erro personalizada ao fluxo de erro.

Um uso típico é colocá-lo depois de um IF, no ramo em que a resposta não é a esperada. O guia IF no n8n: como criar condições no seu fluxo mostra como montar essa condição. No Stop and Error, o parâmetro Error Type tem duas opções:

• Error Message: você escreve a mensagem que será enviada.
• Error Object: você informa um objeto JSON com as propriedades do erro que quer lançar.

Com isso, o fluxo de erro passa a ser acionado também para falhas que o n8n sozinho não trataria como erro.

On Error: o que cada nó faz ao falhar

Os nós têm, na aba Settings, a opção On Error. Ela define o comportamento do nó quando ele dá erro. São três escolhas, descritas na documentação:

• Stop Workflow: interrompe o fluxo inteiro e impede a execução dos nós seguintes.
• Continue: segue para o próximo nó apesar do erro, usando os últimos dados válidos.
• Continue (using error output): segue o fluxo e passa a informação do erro ao nó seguinte, para que ela seja tratada ali. O nó ganha uma saída separada para o erro.

Cuidado com o Continue: como o fluxo segue como se nada tivesse acontecido, o erro pode passar sem aviso. Esta é uma dica prática nossa, e não uma frase da documentação. Prefira a opção com saída de erro quando quiser reagir à falha, por exemplo gravando o problema ou enviando um alerta daquele ponto.

Para ver essa opção num nó que chama APIs, veja o guia HTTP Request no n8n: como chamar uma API no fluxo.

Retry On Fail: tentar de novo

Também na aba Settings, a opção Retry On Fail manda o n8n repetir o nó depois de uma falha. A documentação resume assim: quando uma execução falha, o nó roda de novo até funcionar. Ao ligar a opção, aparecem dois campos:

• Max Tries: o número máximo de vezes que o n8n tenta o nó.
• Wait Between Tries (ms): a espera entre as tentativas, em milissegundos. A documentação dá o exemplo de 1000 para esperar um segundo.

A tela limita os valores desses campos, e a documentação não publica os limites; confira na sua versão. Para esperas longas, a dica prática é usar o nó Wait ou processar em lotes, com o Loop Over Items.

Vale usar Retry On Fail em falhas que podem passar sozinhas, como uma API instável por instantes. Para erros que se repetem, como credencial errada, tentar de novo só atrasa o aviso. Combine as duas opções: o nó tenta de novo e, se continuar falhando, o fluxo de erro pode avisar você.

Exemplo: alerta por e-mail quando um fluxo falha

Este é um modelo simples, montado a partir dos campos que o Error Trigger entrega:

1. Crie o fluxo "Error Handler" com o nó Error Trigger.
2. Adicione um nó de e-mail depois dele. O guia Enviar e-mail no n8n: como usar o nó Send Email mostra a configuração.
3. No assunto, escreva algo como Falhou: {{ $json.workflow.name }}.
4. No corpo, use uma mensagem como esta, montada por nós a partir dos campos da documentação:

Falhou: {{ $json.workflow.name }} no nó {{ $json.execution.lastNodeExecuted }}: {{ $json.execution.error.message }} {{ $json.execution.url }}

1. Salve o fluxo de erro.
2. Abra o fluxo vigiado, vá em Options, Settings, escolha o fluxo no campo Error workflow e salve.

Lembre que o campo execution.url só vem quando a execução está salva no banco de dados. Para ver o alerta funcionar, deixe o fluxo vigiado rodar por um gatilho automático, já que a execução manual não aciona o fluxo de erro.

Vai automatizar tarefas do seu negócio? O n8n Essencial sai a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Conhecer o n8n Essencial

Perguntas frequentes

O que é o Error Trigger no n8n?

É o nó que inicia um fluxo de erro. Quando um fluxo ligado a ele falha, o Error Trigger recebe os detalhes da falha e dispara o aviso que você montou.

Por que meu fluxo de erro não roda quando clico em executar?

Porque, segundo a documentação, não dá para testar fluxos de erro em execuções manuais. Ele só roda quando o fluxo vigiado falha numa execução automática.

Qual a diferença entre Continue e Continue (using error output)?

Nos dois o fluxo segue. No Continue, ele usa os últimos dados válidos. Na opção com saída de erro, a informação do erro vai para o nó seguinte, por uma saída própria, e pode ser tratada.

Qual o número máximo de tentativas do Retry On Fail?

A documentação do n8n não publica esse limite. A tela restringe os valores, então confira os campos Max Tries e Wait Between Tries na sua versão.