Tutorial de tratamento de erros no n8n: retentativas, continuar após falhas e notificações de erro

O maior risco em um fluxo de automação é falhar sem que ninguém perceba: uma API fica temporariamente indisponível, os dados estão em um formato incorreto, uma credencial expira… Se ninguém notar, as notificações podem deixar de ser enviadas por vários dias. Nesta seção, você vai conhecer os mecanismos de tratamento de erros do n8n.

1. Retentativas automáticas (Retry On Fail)

Muitos erros são temporários (instabilidade na rede, timeouts ocasionais de uma API). Na aba Settings do nó:

• Retry On Fail: ative
• Max Tries: número máximo de tentativas, por exemplo, 3
• Wait Between Tries (ms): intervalo entre cada tentativa, por exemplo, 5000 (5 segundos)

Essa opção é indicada para nós que chamam APIs externas (HTTP Request e nós de vários serviços).

2. O que fazer em caso de falha (On Error)

Também na aba Settings do nó, On Error oferece três opções:

Usar a saída de erro

Ao processar vários itens, a falha de um deles não deve interromper os demais:

                    ┌─ success ─▶ [Marcar como processado]
[Chamar API para cada item] ─────┤
                    └─ error ───▶ [Registrar na planilha "Lista de falhas"]

O item com falha inclui uma mensagem de erro, que você pode ler com {{ $json.error.message }}.

3. Interromper a execução: Stop and Error

Quando os dados não estão como esperado, é melhor interromper a execução do que deixar os nós seguintes produzirem resultados incorretos:

[Obter pedido] ─▶ [If o valor está vazio?] ─true─▶ [Stop and Error: "O pedido {{ $json.id }} está sem valor"]
                                            └false─▶ [Continuar o processamento]

O nó Stop and Error faz a execução falhar e aciona o fluxo de tratamento de erros apresentado a seguir.

4. Notificações globais de erro: Error Trigger

Esta é a etapa mais importante: crie um fluxo de trabalho dedicado ao tratamento de erros para receber uma notificação automática sempre que qualquer fluxo falhar.

Criar um fluxo de tratamento de erros

1. Crie um fluxo de trabalho e dê a ele o nome "Notificação de erro".
2. Escolha Error Trigger como primeiro nó.
3. Conecte um nó de notificação (Telegram, Email, Slack etc.) e use esta mensagem:

⚠️ n8n: execução do fluxo de trabalho falhou
Fluxo: {{ $json.workflow.name }}
Nó: {{ $json.execution.lastNodeExecuted }}
Erro: {{ $json.execution.error.message }}
Horário: {{ $now.toFormat('yyyy-MM-dd HH:mm') }}
Ver: {{ $json.execution.url }}

4. Salve. Um fluxo de trabalho iniciado por Error Trigger funciona sem ser publicado.

Atribuir a outros fluxos de trabalho

Em cada fluxo de trabalho que você quer monitorar, acesse: Menu → Settings → Error workflow e selecione "Notificação de erro".

Depois disso, sempre que esse fluxo de trabalho terminar com o status "falha", uma notificação será enviada automaticamente.

O fluxo de tratamento de erros só é acionado quando uma execução automática (agendamento, Webhook etc.) falha. Falhas em testes manuais não o acionam.

5. Consultar e executar novamente

• Em Executions, filtre pelo status Error para ver todas as execuções com falha.
• Abra uma execução com falha e clique em Debug in editor para testá-la novamente com os dados daquela execução.
• Depois de corrigir o problema, você pode executar novamente a execução que falhou.

6. Manter o histórico dos dados

• Em Settings, configure a política de retenção dos registros de execução. Você pode salvar apenas as execuções com falha para economizar espaço no banco de dados.
• Em fluxos importantes, você pode registrar uma entrada ao final em uma planilha ou banco de dados, para consultar depois quando cada item foi processado.

Boas práticas

Crie o hábito de configurar notificações de erro assim que criar um fluxo de trabalho que precisará funcionar por muito tempo.

Atualizado 12 de outubro de 2026