Erreurs 429 dans n8n : maîtriser les rate limits des API OpenAI et Anthropic

Un workflow qui trie 200 emails par IA ou ingère 300 pages de PDF dans une base vectorielle envoie, en quelques secondes, des dizaines d'appels à l'API d'OpenAI ou d'Anthropic. Tant que le volume reste faible, tout passe. Le jour où un client importe son historique complet ou où le digest quotidien traite un lundi matin chargé, l'exécution se couvre de nodes rouges : 429 Too Many Requests. Ce n'est pas un bug de n8n ni de votre prompt — c'est une limite de débit, et elle se corrige avec trois mécanismes précis plutôt qu'en croisant les doigts.

Comprendre ce que mesure vraiment une erreur 429

OpenAI et Anthropic ne facturent pas seulement au token : ils plafonnent aussi le débit, sur plusieurs axes en parallèle :

• RPM (requests per minute) — le nombre d'appels par minute, indépendamment de leur taille ;
• TPM (tokens per minute) — le volume de tokens (entrée + sortie) traité par minute ;
• pour Anthropic spécifiquement, ITPM et OTPM séparent tokens d'entrée et de sortie.

Ces plafonds dépendent de votre palier (tier), qui progresse automatiquement avec l'historique de paiement du compte : chez OpenAI, un compte tout juste crédité de 5 $ tourne par exemple autour de 500 RPM sur GPT-4o, quand un compte établi de longue date peut monter à plusieurs milliers de RPM. Un pack qui fonctionnait parfaitement en test avec dix emails peut donc se heurter à un mur dès qu'il tourne en production sur un vrai volume, sans qu'aucun réglage n'ait changé côté n8n.

Chaque réponse 429 contient des indices précieux : Anthropic renvoie un en-tête retry-after (secondes à attendre) accompagné d'en-têtes anthropic-ratelimit-requests-remaining et anthropic-ratelimit-tokens-remaining qui indiquent laquelle des deux limites a été franchie. OpenAI expose l'équivalent (x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens). Ignorer ces en-têtes et réessayer en boucle sans délai ne fait qu'aggraver la situation.

Premier réflexe : Retry On Fail, mais bien réglé

Sur le node OpenAI, Anthropic ou HTTP Request concerné, l'onglet Settings propose Retry On Fail. Activé seul, il retente immédiatement — inutile face à un rate limit, puisque la fenêtre n'a pas eu le temps de se libérer. Le réglage qui change tout : Wait Between Tries (ms), à pousser largement au-dessus du délai suggéré par retry-after (1 000 à 3 000 ms est un bon point de départ générique). Combiné à 2-3 tentatives maximum, ce seul réglage absorbe déjà les pics isolés — un email en rafale, un pic ponctuel de trafic.

Ce mécanisme reste toutefois local : il protège un appel isolé, pas un traitement par lots. Pour un workflow qui boucle sur des dizaines ou centaines d'items — exactement le cas du tri d'emails ou de l'ingestion documentaire — il faut agir un cran au-dessus.

Loop Over Items (Split in Batches) + Wait : la vraie solution pour les lots

Le node Loop Over Items, historiquement nommé Split in Batches, découpe un ensemble d'items en lots traités un à un plutôt qu'en une seule vague parallèle. Associé à un node Wait placé après l'appel IA et rebouclé vers l'entrée du Loop, il impose une cadence :

1. Loop Over Items — taille de lot réglée sous votre RPM réel (voir calcul ci-dessous).
2. Node IA (chaîne LLM, node Anthropic/OpenAI, ou embeddings) — l'appel qui consomme le quota.
3. Wait — pause fixe entre deux lots (souvent 500 ms à 2 s selon le palier).
4. Retour sur la sortie « loop » du Loop Over Items, jusqu'à épuisement des items ; la sortie « done » prend le relais une fois le lot terminé.

Dimensionnement pratique : divisez votre RPM par 60 pour obtenir un débit par seconde, gardez 20 à 30 % de marge, puis choisissez taille de lot et pause en conséquence. À 500 RPM, viser environ 5-6 appels par seconde revient à un lot de 5 items suivi d'une pause d'une seconde — largement suffisant pour un digest d'emails de plusieurs centaines de messages ou une ingestion de PDF volumineuse comme celle décrite dans notre guide RAG avec Supabase pgvector. Le Pack Assistant RAG et le Pack Inbox IA traitent tous deux des volumes variables par nature ; ce cadencement est la première chose à vérifier si un import massif déclenche des 429 là où un test unitaire passait sans problème.

Respecter le retry-after plutôt qu'un backoff arbitraire

Pour les cas où le rate limit dépend fortement du contenu (TPM plutôt que RPM — un document très long consomme d'un coup une grosse part du quota), un simple cadencement fixe ne suffit pas toujours. La solution robuste consiste à lire l'en-tête retry-after de la réponse d'erreur et à attendre exactement ce délai avant de relancer, plutôt que de deviner un temps d'attente. Concrètement dans n8n :

• Un node HTTP Request appelant directement l'API (plutôt que le node dédié) expose la réponse d'erreur complète, en-têtes compris, exploitable dans un node Code qui suit.
• Sur une erreur 429, ce Code node lit retry-after, ajoute un peu de gigue (jitter, quelques centaines de ms aléatoires) pour éviter que plusieurs exécutions ne redémarrent pile à la même milliseconde, puis pilote un node Wait avec ce délai calculé dynamiquement plutôt qu'une valeur fixe.
• Au-delà de deux ou trois échecs consécutifs sur le même item, mieux vaut le journaliser comme « à retraiter » (une table Supabase dédiée, par exemple) que de s'acharner indéfiniment — le même principe que la piste d'audit décrite dans notre article sur la journalisation RGPD avec Supabase.

Architecture recommandée pour un pipeline IA à fort volume

Sur un traitement asynchrone (digest nocturne, ingestion documentaire, campagne de relance), la combinaison qui tient dans le temps est : une file d'attente Supabase qui reçoit les items à traiter, un trigger cron qui réveille le workflow à intervalle régulier, un Loop Over Items cadencé comme décrit plus haut, et un Error Workflow dédié (voir notre guide sur la gestion des erreurs dans n8n) qui capture les échecs définitifs pour alerte plutôt que de laisser l'exécution mourir en silence. Cette architecture découple le rythme de traitement du rythme d'arrivée des données : que 5 ou 500 emails arrivent d'un coup, le pipeline avance à son propre débit, sans jamais dépasser le quota.

Pièges fréquents

• Paralléliser sans le vouloir : un node Split en amont suivi d'un traitement « pour chaque item » sans Loop Over Items envoie tous les appels quasi simultanément — c'est la cause n° 1 des 429 en production.
• Confondre RPM et TPM : un lot de petits messages respecte le RPM mais peut saturer le TPM si chacun contient un long historique de conversation ; surveillez les deux en-têtes, pas un seul.
• Retry infini sans plafond : sans limite de tentatives, un item durablement problématique (contenu qui déclenche systématiquement une erreur) peut bloquer une exécution entière.
• Oublier le palier du compte : un compte OpenAI ou Anthropic tout juste créé démarre sur le palier le plus bas ; vérifiez vos limites réelles dans la console avant de dimensionner vos lots.

Pour aller plus loin

Ce cadencement — Loop Over Items, Wait, lecture des en-têtes — est déjà intégré dans les workflows d'ingestion et de tri du Pack Inbox IA (79 €) et du Pack Assistant RAG (119 €), dimensionnés par défaut pour rester sous les paliers d'entrée de gamme des deux fournisseurs. Si vous connectez vos propres credentials, notre guide pour connecter Claude ou GPT à n8n couvre la configuration initiale des credentials IA — la brique qui précède naturellement ce cadencement une fois vos workflows en production sur de vrais volumes.