Quand un workflow n8n échoue, le canevas n'affiche souvent qu'une ligne rouge. Les informations utiles se trouvent dans l'historique d'exécution : code HTTP, code d'erreur renvoyé par l'amont, adresse réellement appelée. Avec ces trois éléments, la plupart des erreurs se localisent en quelques minutes.

Cet article les classe par type : 401 et 403 relèvent des identifiants et permissions, 404 vient le plus souvent de la Base URL ou du nom de modèle, 429 du débit et des quotas. Les délais d'attente et échecs de workflow dépendent de la configuration et de l'environnement, et le parsing JSON échoue pour d'autres raisons. Une procédure de diagnostic réutilisable est proposée à la fin, à adapter dans votre propre runbook.

Remarque : n8n et OpenAI sont des marques de leurs détenteurs respectifs ; cet article est indépendant des éditeurs concernés. Les noms de modèles et les prix figurent sur la page Tarifs des modèles ; les champs de nœuds dépendent de votre version.

1. Lisez d'abord l'historique d'exécution

Ouvrez Executions dans la barre latérale, filtrez sur Failed, entrez dans l'exécution en échec et inspectez entrée, sortie et détail de l'erreur nœud par nœud. Notez quatre éléments : nom du nœud, code HTTP, code d'erreur amont et identifiant de requête s'il existe. Ils déterminent si le problème vient de la configuration n8n, de la chaîne réseau ou du service amont.

Un premier classement par code :

Code Signification courante À vérifier en premier
401 Non authentifié ou clé invalide Identifiant sélectionné, expiration de la clé
403 Authentifié mais sans permission Droits sur le modèle, liste blanche IP
404 Adresse ou modèle inexistant Chemin de Base URL, orthographe du modèle
429 Débit limité ou quota épuisé Concurrence, stratégie de relance, quota du compte
400 Paramètres de requête invalides Noms de champs, longueur de contexte, format des messages
5xx Panne temporaire en amont Réessayer plus tard, consulter la page d'état

2. 401 : une clé correcte peut aussi échouer

Une 401 ne signifie pas toujours « mauvaise clé ». Autres causes fréquentes : l'identifiant créé n'est pas sélectionné dans le nœud du workflow ; des espaces ou retours à la ligne ont été collés ; une clé de test a été désactivée ; plusieurs personnes partagent l'instance et le nœud référence un autre jeu d'identifiants ; une instance auto-hébergée a changé de N8N_ENCRYPTION_KEY, rendant les anciens identifiants indéchiffrables.

La marche à suivre est simple : resélectionnez l'identifiant, recollez la clé, enregistrez puis exécutez le nœud seul. Si l'échec persiste, lancez curl sur une machine représentative de l'environnement n8n :

curl -i https://votre-passerelle/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"votre-modele","messages":[{"role":"user","content":"Reponds seulement OK"}]}'

Si curl réussit et n8n échoue, le problème est dans l'identifiant ou le nœud ; si les deux échouent, il est dans la clé, la passerelle ou le réseau. Ne mettez jamais la clé dans un nœud Code, le JSON du workflow ou un champ de commentaire : ces éléments sont facilement exportés et partagés.

3. 404 : Base URL et nom de modèle à parts égales

Dans un identifiant de type OpenAI, la Base URL s'arrête généralement à /v1 ; le nœud ajoute lui-même /chat/completions. Ajouter le chemin complet produit une adresse du type /v1/chat/completions/chat/completions, qui renvoie une 404. À l'inverse, un nœud HTTP Request attend une URL complète et non un simple domaine.

L'autre moitié des 404 vient du nom de modèle. Les services compatibles OpenAI utilisent souvent model_not_found ; l'erreur peut arriver en 404 ou être encapsulée dans une 400. Vérifiez trois choses : la casse, la présence d'un suffixe de date et l'usage d'un alias ou du nom amont d'origine sur la passerelle. Le plus sûr est d'interroger /v1/models et de n'utiliser que des noms présents dans la réponse.

Quelques détails supplémentaires : une barre oblique finale dans la Base URL peut créer un double slash ; si la passerelle est montée sous un sous-chemin de reverse proxy, le préfixe est obligatoire ; après un passage de test à production, l'adresse n'a parfois pas été mise à jour.

4. 429 : les relances ne suffisent pas

Une 429 indique une limitation de débit. Trois déclencheurs courants : dépassement du nombre de requêtes ou de tokens par minute, dépassement de la concurrence, quota ou solde insuffisant. Si l'en-tête Retry-After est présent, respectez-le au lieu de renvoyer immédiatement.

Dans les paramètres du nœud n8n, activez Retry On Fail, fixez le nombre maximal de tentatives à 2 ou 3 et prévoyez un délai croissant. Les relances absorbent les micro-coupures, pas une limitation persistante. Pour les traitements par lots, réduisez la concurrence avec Split In Batches ou Loop Over Items, laissez un intervalle entre les lots, décalez les tâches planifiées et évitez de lancer un débogage sur l'ensemble des données.

5. Délais d'attente et échecs de workflow

Distinguez d'abord les niveaux : délai propre au nœud HTTP Request, délai du workflow, délai du reverse proxy ou de l'équilibreur, durée de génération du modèle amont. La première couche atteinte fait échouer l'exécution, avec un message souvent différent.

Les générations longues dépassent facilement les limites par défaut. Vous pouvez augmenter modérément le délai du nœud, tout en compressant l'entrée, en limitant la sortie et en découpant la tâche. Ne laissez pas un workflow attendre indéfiniment et ne réglez pas un délai si long qu'une panne immobilise longtemps un emplacement d'exécution. Sur une instance auto-hébergée, vérifiez aussi que le processus n'a pas redémarré et que les workers du mode file d'attente sont en ligne.

Configurez également la stratégie d'échec au niveau des nœuds : poursuivre avec On Error en conservant les éléments en erreur pour les lots, arrêter le workflow pour les écritures critiques, puis ajouter un Error Workflow qui envoie l'identifiant d'exécution, le nom du nœud et un résumé de l'entrée vers un canal d'équipe ou une boîte mail. L'échec n'est pas grave ; l'absence de trace l'est.

6. Échec de parsing JSON : une sortie qui n'est pas du JSON

Le message typique est JSON parameter needs to be valid JSON, ou une exception JSON.parse dans un nœud Code. La cause habituelle : le modèle ajoute du texte explicatif ou des balises Markdown autour du JSON, ou les types de champs ne respectent pas le contrat.

Traitez d'abord l'amont : demandez explicitement « uniquement du JSON, sans bloc de code », précisez les champs et les types, et privilégiez la sortie structurée si la passerelle ou le modèle la prend en charge. Le downstream doit tout de même parser défensivement, par exemple dans un nœud Code :

const raw = $json.text ?? $json.content ?? "";
const cleaned = String(raw)
  .replace(/^```(?:json)?\s*/i, "")
  .replace(/```\s*$/, "")
  .trim();

try {
  return [{ json: JSON.parse(cleaned) }];
} catch (e) {
  return [{ json: { parse_error: true, raw: cleaned } }];
}

En cas d'échec, ne supprimez pas silencieusement la donnée : écrivez le texte brut dans une table d'anomalies et inspectez quelques cas, ce qui révèle souvent un problème de prompt ou de capacité du modèle.

7. Une procédure de diagnostic réutilisable

  1. Délimitez la portée : un enregistrement isolé, un lot entier ou tout le workflow.
  2. Reproduisez avec curl depuis le même réseau que n8n pour écarter le nœud.
  3. Comparez l'URL, les en-têtes et le corps réellement envoyés par n8n, surtout la composition de la Base URL.
  4. Interrogez /v1/models pour vérifier le nom, la casse et le suffixe.
  5. Notez code HTTP et code d'erreur : 401, 403 et 404 ne méritent pas de relance ; 429, 5xx et les délais peuvent en mériter.
  6. Vérifiez délais, concurrence et taille des lots avant de modifier les paramètres de relance.
  7. Consignez la conclusion dans le runbook de l'équipe, avec un exemple d'erreur et la correction.

FAQ

n8n renvoie 401 alors que curl fonctionne : où chercher ?

Vérifiez d'abord si le nœud référence le bon identifiant, si la clé contient des espaces ou retours à la ligne, et si l'instance a changé de clé de chiffrement. Vous pouvez aussi ajouter manuellement l'en-tête Authorization dans un nœud HTTP Request pour comparer et déterminer si le problème vient de la résolution des identifiants ou de la construction de la requête.

Une 404 signifie-t-elle toujours une Base URL erronée ?

Non. Un chemin en trop, un /v1 manquant ou un préfixe de reverse proxy perdu produisent aussi une 404 ; un nom de modèle inexistant peut également en renvoyer une. Vérifiez d'abord l'existence du modèle via /v1/models, puis la structure de l'adresse.

Combien de relances pour une 429 ?

En général 2 à 3, avec un délai croissant et le respect de Retry-After. Une 429 persistante signale un dépassement de concurrence ou de quota : continuer à réessayer aggrave la congestion ; réduisez la taille des lots ou décalez l'exécution.

Le workflow réussit mais le résultat est vide : que vérifier ?

Ouvrez l'historique et inspectez la sortie de chaque nœud : le retour du modèle est-il écrasé par un mapping de champs en aval ? La sortie est-elle tronquée ou filtrée par la modération ? Les noms de champs référencés dans les expressions correspondent-ils à la structure réelle de l'étape précédente ?

Quels problèmes réseau surveiller en auto-hébergement ?

Vérifiez que le conteneur ou l'hôte résout et atteint le domaine de la passerelle, ainsi que les variables de proxy, les règles de sortie du pare-feu et la liste blanche IP. Les déclenchements planifiés et les exécutions manuelles peuvent passer par des instances différentes : testez les deux environnements.

Pour aller plus loin

Le principe général du diagnostic : réunir les preuves avant de modifier la configuration, corriger d'abord l'adresse et les identifiants, puis parler de relances et de délais. Pour une entrée compatible OpenAI unifiée, des clés virtuelles distinctes et un journal d'usage, vous pouvez créer un compte sur la passerelle AI de ZSQH ; les modèles et les prix figurent sur la page Tarifs des modèles.

Lectures associées :