Nó de IA do n8n falhou: como saber se é credencial, cota ou queda do provedor

Fala aí, beleza? O fluxo tava rodando de boa no n8n e, do nada, o nó de IA ficou vermelho na execução 😅

O recorte aqui é esse: o nó OpenAI, ou o sub-nó OpenAI Chat Model ligado no AI Agent, falhou. Antes de mexer no fluxo, tu precisa descobrir EM QUAL camada está o problema

A ordem é sempre a mesma: ler a mensagem do nó, conferir a credencial, olhar a cota na conta do provedor e só então abrir a página de status

Se o teu problema é o app do ChatGPT que não carrega no navegador, é outra história. Aqui a falha acontece dentro da automação, com chave de API, limite de uso e retry no meio

Como ler o erro do nó de IA no n8n antes de mudar qualquer coisa

Comece pela execução que falhou e anote o código HTTP e o tipo do erro

Por que começar aqui? Porque o código já diz em qual camada olhar, e mexer no nó antes de ler isso é chute

1. Abra o workflow e vá na aba Executions. Ela lista as execuções anteriores com o status de cada uma (sucesso, falha, em espera), como explica a documentação de execuções do n8n
2. Localize a execução com status de falha e abra
3. Clique em Debug in editor. O n8n carrega no workflow atual os dados daquela execução, pra você corrigir e rodar de novo com a mesma entrada
4. Na mensagem de erro do nó, procure o código HTTP e, quando vier, o tipo do erro. Na OpenAI, os que importam aqui são 401, 429, 500 e 503. Na Anthropic, o erro chega em JSON com um objeto error que traz type e message, além do request_id

Com o código em mãos, o mapa fica assim:

Código	Provedor	Camada	Onde resolve
401 / authentication_error	OpenAI / Anthropic	Credencial	Chave e credencial no n8n
429 rate limit / rate_limit_error	OpenAI / Anthropic	Limite de taxa	Lotes menores e espera
429 insufficient_quota	OpenAI	Cota da conta	Billing da OpenAI
500, 503 / 529 overloaded_error	OpenAI / Anthropic	Provedor	Esperar e tentar de novo

O erro comum deste passo: corrigir o nó e testar com outra entrada qualquer

Aí o teste passa, tu acha que resolveu, e a falha original volta na próxima execução automática… O Debug in editor existe justamente pra repetir com os MESMOS dados que quebraram

Erro 401 no nó OpenAI do n8n: chave ou credencial errada

Se apareceu 401, o problema é de autenticação: a chave está incorreta ou o nó está usando a credencial errada

Sintoma: 401 Invalid Authentication na OpenAI, segundo a documentação de códigos de erro da OpenAI, ou authentication_error na Anthropic

Causa: chave incorreta. A orientação da OpenAI é conferir a chave ou gerar uma nova

Solução:

1. Gere uma chave nova na página de API keys da OpenAI, em Create new secret key
2. No n8n, abra a credencial OpenAI e cole a chave no campo API Key, que é o único obrigatório. Organization ID e Base URL são opcionais, como mostra a doc da credencial OpenAI no n8n
3. Volte no nó que falhou e confira se ele está ligado a essa credencial, e não a outra com nome parecido
4. Rode de novo pelo Debug in editor, com a mesma entrada da falha

Como prevenir: nomeie as credenciais por conta e projeto, tipo OpenAI | Cliente X | Produção

Parece frescura, mas é isso que evita ligar o nó na chave da conta errada quando tu tem várias credenciais parecidas no mesmo n8n =)

Erro 429 no n8n: rate limit ou cota insuficiente?

Na OpenAI, o mesmo 429 tem duas causas bem diferentes, e a correção de uma não resolve a outra

O tipo do erro é o que separa os dois casos, por isso vale ler a mensagem inteira e não só o número

Rate limit: requisições demais em pouco tempo

Aqui a conta está ok, o fluxo é que está mandando requisição rápido demais

A página de problemas comuns do nó OpenAI indica duas saídas:

• Dividir os dados com o nó Loop Over Items e colocar um nó Wait no fim do loop
• Ou chamar a API da OpenAI pelo nó HTTP Request usando a opção de limite de lote (batching)

E como saber qual é o teu limite? As respostas da API da OpenAI trazem cabeçalhos de rate limit, como x-ratelimit-limit-requests, x-ratelimit-remaining-requests e x-ratelimit-reset-requests, além dos equivalentes para tokens

Na Anthropic, o equivalente é o 429 rate_limit_error, que indica que a conta atingiu o rate limit

insufficient_quota: a cota acabou

Esse é o 429 de dinheiro: créditos esgotados ou teto de gasto mensal atingido, e a OpenAI manda resolver no billing

O checklist da documentação do n8n pra cota insuficiente:

1. Confirme que há crédito na conta da OpenAI
2. Gere uma nova API key
3. Confira se a credencial usa a chave da conta onde o crédito foi colocado e se o nó está ligado nessa credencial
4. Se você preencheu o Organization ID, confira se ele aponta pra organização certa, porque é ele que define qual cota é consumida
5. Olhe a página de limites de uso da organização
6. Se quiser, ligue a recarga automática no billing da OpenAI

Se liga no item 4: já vi muita gente colocar crédito numa organização e deixar o Organization ID apontando pra outra, aí o erro continua e parece mistério haha

Como prevenir: lotes menores e espera entre os lotes pro rate limit

E NUNCA tente resolver cota com retry: sem crédito, cada nova tentativa vai bater no mesmo 429

Erro 500, 503 ou 529: quando a falha é do provedor de IA

Aqui a culpa não é tua: 500 indica problema nos servidores da OpenAI, 503 indica servidores sobrecarregados e, na Anthropic, 529 overloaded_error indica API temporariamente sobrecarregada

Nos três casos, a orientação dos provedores é a mesma: esperar um pouco e tentar de novo

Checagem: abra a página de status do provedor

• OpenAI: status.openai.com
• Anthropic: status.claude.com

Tome cuidado com um detalhe: as duas páginas mostram vários componentes. Na OpenAI tem API, ChatGPT e outros; na Anthropic tem claude.ai, Claude Console, Claude API e Claude Code

O que importa pro n8n é o componente da API, não o do app de chat. Confira também o histórico de incidentes pra ver se a janela da tua falha bate com algum

Agora, se o status está verde e o erro nem traz código da API do provedor, a desconfiança vira pro teu lado: vale olhar a própria instância do n8n. Quem hospeda num servidor próprio deve caprichar na escolha da VPS para n8n e em manter o n8n rodando 24/7 sem quedas

Como prevenir: retry com espera entre tentativas, que é exatamente o próximo bloco

Como configurar Retry On Fail e caminho de erro no nó de IA

Essa é a decisão central do post: retry serve pra falha passageira, e caminho de erro serve pra todo o resto

Antes do como, o porquê: retry em erro de credencial ou cota só repete a falha. Já em sobrecarga do provedor ou rate limit momentâneo, uma segunda tentativa com espera costuma ser o suficiente

Erro	Retry ajuda?
500, 503, 529	Sim
429 rate limit passageiro	Sim, com espera
401 / authentication_error	Não
429 insufficient_quota	Não

1. Abra o nó e vá na aba Settings
2. Ligue Retry On Fail. Aparecem dois campos: Max. Tries (quantas tentativas) e Wait Between Tries (ms) (espera entre tentativas, em milissegundos), como descreve a doc de trabalho com nós do n8n
3. Escolha o comportamento em On Error, que tem três opções:

– Stop Workflow: a execução para ali – Continue: segue o fluxo – Continue (using error output): manda os dados do erro pra uma saída separada, que tu trata mais adiante no workflow

Um exemplo mínimo, só com os campos que existem (os valores são escolha tua, a documentação oficial não traz número recomendado):

Nó de IA > Settings
  Retry On Fail: ligado
  Max. Tries: <quantas tentativas você aceita>
  Wait Between Tries (ms): <espera entre tentativas>
  On Error: Stop Workflow

Como isso fica Stop Workflow, quem avisa da falha é o error workflow do próximo bloco

O erro comum deste passo: ligar Retry On Fail e deixar On Error numa das opções Continue

Nessa combinação, o n8n ignora Max. Tries e Wait Between Tries, comportamento relatado na issue #9236 do n8n no GitHub. Não tenho confirmação se isso já mudou em versão recente, então teste no teu fluxo antes de confiar nos dois juntos

Se o teu fluxo usa AI Agent com sub-nó de modelo, confira na documentação do sub-nó como ele se comporta, porque aqui estou falando das Settings do nó em si

Como montar um error workflow para avisar quando a IA falhar

O error workflow é um workflow separado que roda quando outro falha, e é ele que te avisa em vez de tu descobrir dias depois na aba Executions

1. Crie um workflow novo começando pelo nó Error Trigger, como mostra a doc de tratamento de erros do n8n
2. Depois do Error Trigger, coloque o que vai te avisar (o canal de notificação que tu já usa)
3. No workflow principal, vá em Options > Settings > Error workflow, selecione o workflow de erro e clique em Save
4. Se quiser forçar uma falha sob uma condição tua (por exemplo, a IA respondeu algo fora do formato esperado), use o nó Stop And Error. Ele tem a operação Error Message (mensagem personalizada) e Error Object (objeto JSON), e manda esse erro pro error workflow

Checagem final e erro comum: o Error Trigger só dispara quando um workflow automático falha

Ou seja, rodar o workflow na mão pelo editor NÃO testa o error workflow. Já me ferrei com isso achando que a configuração estava quebrada 😛

Outros dois detalhes da doc: o workflow com Error Trigger não precisa estar ativado, e o mesmo error workflow pode servir vários workflows. Um só já cobre todos os teus fluxos com IA

O que o curso de n8n mostra sobre montar o agente de IA

No vídeo eu monto o fluxo do zero até o agente de IA, usando a OpenWeatherMap como exemplo de serviço que pede credencial

É uma boa pra ver o fluxo inteiro montado antes de sair caçando erro =)

Se tu ainda está montando o fluxo, o vídeo completo tá aqui:

Conclusão

Abre agora a aba Executions do workflow que falhou, anota o código e o tipo do erro e aplica só a correção daquela camada

Depois decide a proteção pelo tipo de falha: retry com espera pro que é passageiro, error output ou error workflow pro resto

Se o teu nó é o sub-nó OpenAI Chat Model dentro do AI Agent, ele tem uma página de problemas comuns própria na documentação do n8n, vale dar uma lida antes de mexer

Até o próximo post! 🙂

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.