Erro 429 no n8n: quando usar Retry On Fail, Wait e Batching

Para corrigir o erro 429 no n8n, identifique o limite da API, reduza o ritmo das chamadas e defina uma política limitada de retentativas. Use Retry On Fail para falhas recuperáveis, Wait com Loop Over Items quando precisar controlar o percurso e Batching para espaçar requisições no HTTP Request. Nenhuma dessas opções aumenta a cota contratada nem torna uma operação de escrita segura para repetir.

Confirme o limite antes de alterar o fluxo

O status 429 Too Many Requests indica excesso de requisições em determinado período. A resposta pode trazer detalhes e o cabeçalho Retry-After. Isso não informa, por si só, qual usuário, chave, rota ou janela está limitada: consulte o contrato da API e a resposta recebida. Essa definição está na especificação do status 429.

Abra a execução que falhou e anote o nó, o horário, o status, o corpo da resposta e o identificador da requisição, quando fornecido. O n8n apresenta a mensagem retornada pelo serviço no painel do nó, conforme o guia de limites de taxa. Diferencie a resposta da API de um timeout local: no segundo caso, o servidor pode ter recebido a operação sem que o fluxo tenha obtido a confirmação.

Confira o escopo da restrição. Um limite por credencial pode ser compartilhado por outros workflows; um limite por rota pode afetar somente uma operação. Verifique também se cada item dispara chamadas adicionais, paginação ou busca de detalhes. Reduzir o lote de um único nó ajuda pouco quando outras execuções continuam consumindo a mesma cota. Essa análise do conjunto é uma recomendação de operação, não um contador global criado automaticamente pelo Batching.

Quando usar Retry On Fail

Em Settings do nó, a opção Retry On Fail permite tentar novamente após uma falha. O intervalo Wait Between Tries é configurado em milissegundos. Use um número finito de tentativas e uma pausa compatível com o limite do serviço. A sequência de configuração está no manual de tratamento de rate limits.

Esse recurso é adequado quando repetir aquela operação faz sentido e a pausa configurada atende à regra conhecida. Ele não significa que todo erro deve ser repetido: credencial inválida, campo obrigatório ausente ou operação recusada por permissão pedem correção da causa. Examine o código e a mensagem específicos do provedor, em vez de tratar qualquer falha como um congestionamento passageiro.

Antes de habilitar retentativas em criação de pedidos, cobranças ou mensagens, defina como reconhecer uma operação já concluída. Quando a API oferecer chave de idempotência, reutilize a chave da mesma operação lógica conforme o contrato dela. Se não oferecer, avalie consulta por identificador externo e deduplicação durável. Essas medidas exigem desenho da integração; marcar Retry On Fail não as implementa.

Também confira o comportamento do nó com vários itens e com respostas parciais. Uma falha não apaga necessariamente os efeitos já produzidos no sistema externo. Guarde os identificadores confirmados e evite reiniciar uma lista inteira sem saber quais registros foram processados. O objetivo é retomar o trabalho pendente, não transformar cada nova tentativa em outra operação comercial.

Como controlar o ritmo com Batching ou Loop e Wait

No HTTP Request, adicione a opção Batching. Configure Items per Batch e Batch Interval, cujo intervalo é em milissegundos. Esses campos organizam o processamento dos itens e a pausa entre lotes, conforme a documentação do HTTP Request. Eles não transformam uma rota comum em endpoint de importação em massa.

Como exemplo hipotético, uma API pode permitir uma chamada por segundo. Um item que gera apenas uma requisição é diferente de outro que consulta dados, busca detalhes e grava o resultado. Calcule o consumo pelas chamadas efetivas, não apenas pela quantidade de linhas da planilha. Comece com uma margem operacional e observe as respostas; não trate uma divisão matemática da cota como garantia de ausência de 429.

Quando houver mais etapas por item, coloque Loop Over Items antes da integração, processe o lote, acrescente Wait e conecte o retorno ao loop. O caminho de conclusão segue para a próxima etapa após os lotes. O nó de loop organiza os itens; o nó Wait controla a pausa. Confira essas ligações em uma cópia do workflow antes de executar a lista real.

Escolha Batching quando o controle cabe no próprio HTTP Request. Prefira um loop explícito quando precisar consultar estado, aplicar uma regra por item ou variar a espera. Evite empilhar Batching, Wait e retentativas sem um plano: a combinação pode aumentar bastante a duração sem resolver o limite compartilhado. Registre qual mecanismo previne a sobrecarga e qual recupera uma falha.

Retry-After não é sempre uma quantidade de segundos

O valor de Retry-After pode ser uma data HTTP ou um número inteiro de segundos. Portanto, não multiplique qualquer texto recebido por mil. Primeiro identifique o formato; se for data, calcule a diferença para o instante atual. A regra dos formatos está na especificação HTTP, seção Retry-After.

Para examinar status e cabeçalhos no HTTP Request, use Include Response Headers and Status. Se decidir tratar códigos de erro dentro do fluxo com Never Error, acrescente uma verificação explícita do status: essa opção faz o nó retornar sem falhar também para respostas que não seriam sucesso. A descrição está nas opções de resposta do nó. Não deixe um 429 seguir pelo mesmo caminho de uma gravação confirmada.

Sem uma orientação utilizável do provedor, uma política editorial possível é aumentar a pausa entre tentativas, com limite de tempo e de quantidade. Esse é o princípio do backoff exponencial. Uma pequena variação aleatória pode evitar que várias execuções retornem juntas. Esses controles precisam ser implementados conforme o seu fluxo; não presuma que uma espera fixa no Retry On Fail virou backoff automático.

Defina uma saída para quando o orçamento de recuperação terminar. Registre a operação pendente, sua chave externa e a última resposta relevante, depois encaminhe para revisão ou reprocessamento controlado. Não mantenha um ciclo sem fim entre Wait e a mesma requisição. Quando o serviço continuar recusando chamadas, pausar a fila e investigar a restrição pode ser mais útil do que multiplicar as tentativas.

O controle precisa considerar outros workflows

Se várias execuções compartilham a mesma credencial, o orçamento de chamadas pertence ao conjunto delas. Uma pausa local não coordena outros workflows, integrações externas ou processos manuais usando a chave. Para cargas recorrentes, considere uma fila de trabalho ou um controle compartilhado de consumo, com liberação gradual e estado durável. Essa é uma recomendação de arquitetura, não um efeito automático de Wait.

Um exemplo hipotético é a importação que funciona isolada, mas falha quando a rotina de atualização inicia ao mesmo tempo. Nesse caso, diminuir o lote de cada processo pode reduzir a disputa, enquanto uma fila compartilhada permite ordenar o trabalho. Verifique quem usa a credencial antes de aumentar paralelismo ou contratar mais capacidade. A informação necessária está no consumo e no limite efetivo do serviço.

Como decisão de operação, diferencie tarefas que podem aguardar de consultas necessárias ao atendimento imediato. Uma importação de fundo não deveria consumir sem controle o mesmo orçamento usado por uma ação urgente. Registre a prioridade, os itens pendentes e o ponto de retomada. Essa organização ajuda a pausar a carga volumosa sem perder o controle do trabalho já confirmado.

Registre volume processado, operações pendentes, respostas 429, duração da espera e tentativas por operação. Para fluxos que devem avisar sobre falhas, o n8n oferece o Error Trigger como parte do tratamento de erros. Uma resposta desviada para um caminho normal pode exigir monitoramento próprio; não suponha que todo problema tratado produzirá uma execução marcada como falha.

Como validar sem arriscar uma importação inteira

Teste em homologação com uma amostra representativa, incluindo sucesso, limitação de taxa, erro permanente e resposta incerta. Confira se a espera foi aplicada, se o fluxo encerra as retentativas e se a retomada preserva os registros já confirmados. Em operações de escrita, a aprovação depende do estado no destino, não apenas da cor da execução do n8n.

• Confira no provedor a janela, a unidade e o escopo do limite.
• Meça chamadas reais por item, incluindo paginação e consultas auxiliares.
• Verifique o formato de Retry-After e as unidades usadas no Wait.
• Defina como identificar uma operação já concluída antes de repeti-la.
• Confirme a saída de erro e o registro dos itens pendentes.
• Compare o comportamento isolado com a carga concorrente esperada.

Depois de ajustar, acompanhe uma execução nova desde a entrada. Reexecutar apenas um nó intermediário ajuda no diagnóstico, mas não comprova que gatilhos, filas e controles anteriores funcionam juntos. Preserve as configurações anteriores para retorno e documente o motivo da pausa escolhida, em vez de deixar um número sem relação com o contrato da API.

Perguntas frequentes sobre erro 429 no n8n

Aumentar o tempo de espera sempre resolve?

Não. A restrição pode ser compartilhada ou usar uma janela diferente da esperada. Uma pausa adequada a um processo isolado pode ser insuficiente com outros consumidores. Leia a resposta do serviço e confirme o escopo antes de alterar o intervalo novamente.

Batching é o mesmo que enviar tudo em uma chamada?

Não presuma isso. A opção organiza os itens processados pelo nó. Para enviar vários registros em um único corpo, a API precisa oferecer e documentar uma operação em lote, e o workflow deve montar esse corpo no formato aceito.

Posso habilitar Never Error para o fluxo parar de falhar?

Você pode usá-lo para construir um tratamento explícito do status. Se apenas esconder a falha e continuar, o workflow pode indicar sucesso sem concluir o trabalho. O caminho de limitação, a saída de erro e a confirmação do destino precisam continuar verificáveis.

Qual estratégia escolher

Para uma falha recuperável pontual, comece com Retry On Fail limitado e repetição segura. Para listas previsíveis no HTTP Request, avalie Batching. Para regras variáveis, use Loop Over Items e Wait com encerramento explícito. Quando vários processos disputam a cota, coordene o conjunto. O ajuste correto combina ritmo compatível, retomada sem duplicidade e evidência de que a operação terminou no destino.