Tratamento de Erros no n8n

Quando Usar

Use esta habilidade para fluxos de trabalho não supervisionados, contratos de resposta de webhook/API, design de retentativas, saídas de erro, fluxos de trabalho de Gatilho de Erro, alertas ou qualquer caminho onde a falha deva ser visível e recuperável.

Faça as retentativas serem limitadas e idempotentes, especialmente para envios, pagamentos e gravações. Redija credenciais, dados pessoais, corpos de requisição e detalhes de stack de respostas e alertas voltados para o chamador; exponha apenas o contexto diagnóstico mínimo necessário.

Por padrão, quando um nó do n8n falha, o fluxo de trabalho inteiro para. Para uma execução interativa que você está observando, tudo bem — você vê o nó vermelho e o corrige. Para qualquer coisa não supervisionada (uma API de webhook, um trabalho cron, um worker de fila, uma ferramenta de agente), esse é o padrão errado: o chamador recebe um timeout ou um 500 vazio, o operador não recebe alerta, e o sintoma é "a integração simplesmente parou de funcionar" sem log e sem pista.

Esta habilidade trata de tornar as falhas altas, estruturadas e recuperáveis — e, no melhor dos casos, auto-reparáveis, para que falhas transitórias nunca cheguem a um humano.

As duas ideias que previnem a maioria das falhas silenciosas:

• Saídas de erro por nó — a falha de um nó é roteada para uma segunda saída que você controla, em vez de encerrar a execução.
• Um fluxo de trabalho de erro em nível de fluxo de trabalho — um "catch-all" que dispara para qualquer coisa que escape do tratamento por nó (timeouts, travamentos entre nós, falhas não conectadas).

Quando você realmente precisa disso

A linha divisória: se alguém além de você vir a saída — um sistema downstream, um usuário final, um engenheiro de plantão — a falha tem que ser tratada, não engolida. Se você é o único observador e o custo da falha é "eu percebo e reexecuto", um tratamento mais flexível está bom.

A armadilha silenciosa #1: a saída de erro por nó é uma configuração de DUAS etapas

Esta é a maneira mais comum de um fluxo de trabalho n8n "tratar" erros enquanto, na verdade, os engole. Roteamento da falha de um nó para um manipulador leva duas mudanças, e fazer apenas uma parece completo, mas se comporta mal:

1. Defina onError: "continueErrorOutput" no nó. Isso é o que cria a segunda saída. Sem isso, main[1] não existe, não importa o que você conecte.
2. Conecte essa saída de erro (connections.<node>.main[1], ou seja, sourceIndex: 1) a um manipulador real. Sem um destino, os dados de erro são emitidos para o vazio.

Obtenha um sem o outro e você atinge um modo de falha:

Fazendo ambos com n8n_update_partial_workflow

// 1) Turn on the error output (creates main[1])
{ type: "updateNode", nodeName: "HTTP Request",
  changes: { onError: "continueErrorOutput" } }

// 2) Wire the error output to a handler. sourceIndex: 1 = the error output.
{ type: "addConnection",
  source: "HTTP Request",
  target: "Handle Error",
  sourceIndex: 1 }

sourceIndex: 0 é o caminho de sucesso, sourceIndex: 1 é o caminho de erro. (Para nós IF, os aliases branch: "true"/"false" mapeiam para os índices 0/1; para um nó falível genérico, use o sourceIndex: 1 explícito.)

Em seguida, verifique. Esta armadilha não aparece em validate_workflow — uma saída de erro parcialmente conectada valida limpa. Puxe o fluxo de trabalho com n8n_get_workflow e confirme ambas as metades:

• O onError do nó é "continueErrorOutput".
• connections["HTTP Request"].main[1] contém seu manipulador.

Valores válidos de onError:

…