Uma automação pode terminar com erro depois de já ter realizado parte do trabalho. O cadastro entrou no CRM, mas a confirmação não chegou; quatro documentos foram processados, mas o quinto interrompeu o lote. Nesses casos, repetir tudo sem conferir o resultado anterior pode criar outro problema.
Uma fila de falhas organiza o que ainda precisa de intervenção. Neste guia, ela é uma estrutura persistente criada pela equipe, integrada aos workflows do n8n. O objetivo é identificar cada item pendente, entender a falha e controlar sua recuperação.
Resumo rápido
- Separe o registro do erro da decisão de tentar novamente.
- Controle o resultado de cada item e de cada ação externa.
- Reprocesse somente pendências elegíveis, com limites e conferência no destino.
1. Entenda o que o n8n já oferece
O n8n permite associar um workflow de erro a outros workflows. Esse tratamento começa com o Error Trigger e recebe informações da execução que falhou. A documentação de tratamento de erros mostra como configurar essa associação e informa que alguns campos dependem de a execução ter sido salva.
A fila proposta aqui acrescenta um controle de negócio: qual solicitação continua pendente e qual etapa pode ser repetida. O alerta de falha informa que houve um problema; o registro persistente permite acompanhar sua resolução.
Outro detalhe afeta os testes: segundo a documentação do Error Trigger, ele dispara quando uma execução automática falha, não durante uma execução manual de teste. Valide o tratamento com um evento automático controlado, usando dados fictícios e um destino de testes.
2. Registre a pendência antes de escolher a recuperação
Use uma tabela persistente, com identificador único da operação. Guarde a referência da solicitação original, a etapa que falhou, o motivo resumido, o número de tentativas, a próxima tentativa permitida e o estado atual. Registre também os identificadores devolvidos pelos serviços que já concluíram suas ações.
Estados úteis incluem pendente, em_processamento, resolvido e revisao_necessaria. A passagem de pendente para processamento precisa impedir que dois trabalhadores assumam o mesmo item simultaneamente. Essa coordenação pertence ao armazenamento e ao desenho do fluxo.
Evite copiar senhas, tokens ou o conteúdo integral de conversas para a fila. Prefira uma referência para o registro autorizado e os dados mínimos necessários à recuperação. A retenção deve acompanhar a necessidade operacional definida pela equipe.
3. Diferencie falhas transitórias, permanentes e resultados incertos
Uma indisponibilidade temporária pode justificar nova tentativa. Um campo obrigatório ausente precisa de correção. Uma credencial revogada exige intervenção. Já um timeout depois do envio de um pedido deixa uma dúvida: o destino pode ter concluído a ação mesmo sem devolver a confirmação.
Essa classificação deve considerar a operação e a resposta do serviço. Não transforme todo erro em uma repetição automática. Para cada integração, documente quais condições permitem tentar novamente, quais interrompem o processo e quais exigem consultar o destino primeiro.
Defina um teto de tentativas e intervalos crescentes, respeitando as orientações de espera que a API fornecer. São parâmetros da operação, não números universais. Quando várias solicitações falham pela mesma indisponibilidade, considere pausar novas chamadas; o guia sobre circuit breaker em agentes de IA aprofunda essa decisão.
4. Reprocesse a unidade certa
A documentação atual de execuções do n8n esclarece que uma repetição retoma o estado salvo. Resultados de nós concluídos são preservados, mas o nó que falhou recebe novamente sua entrada e processa todos os itens, inclusive aqueles que ele pode ter tratado antes de falhar. Por isso, confira os efeitos desse nó no serviço de destino.
Para operações críticas, organize o processamento por item ou mantenha um registro por item dentro do lote. Antes de repetir uma ação, verifique se existe resultado confirmado para sua chave de operação. Se o provedor aceitar idempotência, reutilize a mesma chave para a mesma ação, conforme o contrato daquela API.
Não marque um item como resolvido apenas porque o nó terminou sem erro. Grave a evidência pertinente: identificador do registro criado, estado retornado pelo serviço ou confirmação consultada no destino. A proteção contra eventos repetidos também aparece no artigo sobre webhooks e processamento duplicado.
5. Exemplo hipotético: documentos recebidos de fornecedores
Imagine um fluxo que recebe dez documentos, valida os campos e registra cada um no sistema administrativo. Oito concluem a etapa. Um documento está sem identificação do fornecedor; outro recebe uma resposta de indisponibilidade temporária.
O documento incompleto vai para revisão, com o campo ausente destacado. O segundo permanece elegível para nova tentativa. Os oito concluídos ficam fora da recuperação. Se a indisponibilidade aparecer como timeout, confira se o serviço chegou a aceitar o documento antes de perder a conexão. A consulta pelo identificador da operação pode revelar esse resultado.
Após corrigir o campo ausente, a equipe libera somente aquele item. O histórico preserva a falha inicial, a correção e a conclusão, permitindo entender o que ocorreu sem reconstruir toda a execução.
Checklist para colocar em operação:
- Definir a unidade recuperável: documento, pedido ou mensagem.
- Registrar entrada, etapa, tentativas e resultado por identificador único.
- Separar revisão humana, repetição permitida e resultado incerto.
- Testar falha parcial, processamento concorrente e indisponibilidade do destino.
- Acompanhar pendências antigas e impedir repetição ilimitada.
Perguntas frequentes
A fila de falhas é um recurso que basta ativar no n8n?
Neste desenho, ela é uma estrutura criada pela equipe. O n8n fornece os workflows e os recursos documentados de tratamento e repetição; a tabela e as regras de recuperação precisam ser implementadas.
Qual indicador acompanhar primeiro?
Comece pela idade da pendência mais antiga e pelo total de itens que precisam de intervenção. Isso ajuda a distinguir um erro recuperado de uma solicitação esquecida.
