Les erreurs de Dify se répartissent en deux couches : celles qui surviennent lors de l'appel à l'API de l'application, et celles que Dify rencontre lorsqu'il appelle un fournisseur de modèles. Les deux couches peuvent renvoyer 401, 404 ou 429, mais les objets à examiner sont totalement différents. Se focaliser sur le code de statut conduit souvent à modifier encore et encore la configuration de la mauvaise couche.

Cet article décompose les problèmes courants selon six niveaux — authentification, adresse, limitation de débit, workflow, contexte, journaux — et fournit des commandes de reproduction minimales ainsi qu'un ordre de diagnostic fixe. Les codes d'erreur, les quotas et les noms d'interface font foi selon la documentation de Dify et des fournisseurs de modèles.

Remarque : Dify est une marque de son détenteur. Cet article n'a aucun lien d'affiliation avec les sociétés concernées ; les autres noms de produits cités appartiennent à leurs détenteurs respectifs. Les versions décrites correspondent aux versions courantes d'octobre 2026.

1. Séparer d'abord trois couches, sans deviner

Une requête traverse au minimum trois couches : le client, l'API de l'application Dify et le fournisseur de modèles, avec éventuellement une passerelle entre elles. Un 401 peut provenir du client vers Dify ou de Dify vers l'amont ; un 404 peut signaler un chemin erroné ou un nom de modèle incorrect ; un 429 vient le plus souvent de l'amont.

Commencez par lire les champs message, code et l'identifiant de requête dans le corps de la réponse, puis décidez quelle couche examiner. Règle pratique : appelez directement l'API de l'application avec curl. Si la même erreur apparaît, le problème vient de la configuration Dify ou de l'amont ; si curl fonctionne alors que le code métier échoue, le problème vient du client ou du réseau.

2. 401 et 403 : ne pas mélanger les deux types de clés

Dify utilise deux jeux d'identifiants : la clé API d'application sert à appeler une application Dify, tandis que la clé du fournisseur de modèles sert à Dify pour appeler le modèle en amont. La première se place dans l'en-tête Authorization: Bearer ..., la seconde se configure dans les paramètres du fournisseur. Leur mélange est la cause la plus fréquente des 401.

Causes courantes :

  • L'en-tête omet Bearer, ou la clé contient des espaces, un saut de ligne ou des guillemets.
  • La clé utilisée appartient à une autre application. Une clé d'application est généralement créée par application et ne peut pas être réutilisée ailleurs.
  • La clé a été supprimée ou renouvelée, ou l'espace de travail n'a pas accès à cette application.
  • La clé du fournisseur est expirée, sans solde, révoquée, ou un caractère a été perdu lors de la copie.
  • Un proxy inverse, une passerelle ou le front-end filtre l'en-tête Authorization.

Les 403 relèvent surtout des permissions : rôle insuffisant dans l'espace de travail, modèle sans accès chez le fournisseur, compte amont restreint. Vérifiez d'abord « qui appelle qui », puis retestez avec une autre clé.

3. 404 et modèle inexistant : vérifier l'adresse et le nom

Lors d'un appel à l'API d'une application Dify, les 404 relèvent généralement de trois cas :

  1. URL de base erronée : l'URL de base de l'API d'application de Dify Cloud est https://api.dify.ai/v1 ; en auto-hébergement, utilisez votre domaine et votre chemin. Omettre /v1 ou ajouter le chemin complet de l'interface provoque un 404.
  2. Point de terminaison incompatible avec le type d'application : une application de chat utilise chat-messages, une application de workflow utilise workflows/run, une application de génération de texte utilise completion-messages. Avec un mauvais point de terminaison, même une clé correcte renvoie 404 ou 400.
  3. Chemin réécrit par le proxy inverse : sous-chemin Nginx, barre oblique finale ou règles de réécriture d'URL peuvent diriger la requête vers une route inexistante.

Si l'erreur vient du fournisseur de modèles, les messages habituels sont model not found, model does not exist ou invalid model. Vérifiez que l'identifiant du modèle correspond au nom actuellement proposé, y compris la casse, le suffixe de date et les alias ; confirmez que le modèle est activé dans Dify ; vérifiez que la version du plugin prend en charge ce modèle. Le retrait ou le renommage d'un modèle invalide aussi une configuration existante.

4. 429 : débit, concurrence et quotas

Un 429 n'est généralement pas renvoyé par Dify, mais par le service de modèles en amont ou la passerelle, qui indique « trop de requêtes ». Le déclencheur peut être le nombre de requêtes par minute, le nombre de tokens par minute, la concurrence ou le quota du compte. Les tâches par lots, les nœuds de boucle et l'usage simultané par plusieurs personnes font monter la concurrence instantanée.

Ordre de traitement :

  • Lire d'abord les en-têtes de réponse et le message d'erreur pour distinguer fréquence de requêtes, débit de tokens et limite de concurrence.
  • Réduire la concurrence côté client, ajouter une file aux tâches par lots, ne pas saturer en une seule fois.
  • Ne réessayer que les 429 et les 5xx, avec un backoff exponentiel et une gigue aléatoire, et fixer un nombre maximal de tentatives.
  • Pour les workflows, tenir compte de l'idempotence : une même requête métier peut exécuter plusieurs fois un nœud ; ajoutez si possible une clé de déduplication au niveau métier.
  • En cas de déclenchements fréquents sur la durée, envisagez de diviser l'application, les clés ou les projets, ou de décaler les plages d'appel.

Réessayer à l'aveugle transforme la limitation de débit en avalanche. Avant de réessayer, vérifiez si la requête a déjà produit des effets de bord.

5. Échec de workflow : partir des entrées et sorties des nœuds

Un échec global de workflow se localise généralement sur un nœud précis. Types courants :

Symptôme Cause fréquente À vérifier en premier
Référence de variable vide Le nœud amont ne produit pas cette variable, ou le nom est mal orthographié Structure de sortie du nœud et sélecteur de variable
Type incompatible Une chaîne utilisée comme tableau ou objet Type renvoyé par le nœud amont et nœud de conversion
Erreur du nœud de code Syntaxe, dépendance, délai d'attente ou structure de retour non conforme Journaux d'exécution et contrat du nœud de code
Échec du nœud HTTP Réponse non 2xx, authentification, délai d'attente, certificat Code de statut, en-têtes, journaux du service cible
Échec d'analyse de la sortie LLM Le modèle ne respecte pas le format JSON Contraintes du prompt et tolérance de l'analyseur
Récupération de connaissances vide Indexation inachevée, seuil trop élevé, échec de réécriture de requête État de la base de connaissances et paramètres de rappel
Échec du nœud d'itération Entrée qui n'est pas un tableau, ou sous-flux mal référencé Entrée d'itération et structure d'un élément

Les workflows Dify prennent en charge la gestion d'erreur au niveau du nœud : nouvelle tentative, valeur par défaut ou branche d'exception. Mieux vaut prévoir un filet pour les nœuds critiques que de laisser échouer toute la chaîne. Mais n'utilisez pas une valeur par défaut pour masquer une erreur de configuration : le problème n'apparaîtrait que plus tard, en aval.

6. Contexte et limite de tokens

Les erreurs de contexte se manifestent souvent par un 400 avec context length exceeded, maximum context ou token limit. La cause n'est pas « le modèle est mauvais », mais un volume total entrée plus sortie supérieur à la limite permise. Ce volume comprend le prompt système, l'historique de conversation, les extraits récupérés de la base de connaissances, la saisie utilisateur et la sortie réservée.

Pour diagnostiquer, compressez point par point :

  • Limiter le nombre de tours d'historique, ou résumer avant de concaténer.
  • Réduire le nombre d'extraits récupérés, activer le reranking, supprimer les passages hors sujet.
  • Ajuster la taille de découpage des documents pour éviter des blocs trop longs.
  • Fixer séparément un maximum de tokens de sortie et laisser une marge à l'entrée.
  • Estimer les tokens côté application, tronquer avant dépassement ou basculer vers un modèle à contexte plus long.

La longueur de contexte configurée dans Dify doit correspondre à la valeur réellement prise en charge par le fournisseur. Une valeur supérieure à celle de l'amont fait rejeter la requête ; une valeur trop faible tronque prématurément les documents longs.

7. Journaux et traçage : relier une requête de bout en bout

Le diagnostic ne doit pas se limiter au dernier message. Conservez au moins quatre types d'informations : les journaux d'application et les enregistrements de workflow Dify, les journaux du fournisseur de modèles, les journaux de requêtes de la passerelle, et côté métier l'utilisateur et l'identifiant de requête. L'historique d'exécution de Dify montre les entrées, sorties et durées de chaque nœud : c'est le premier point d'entrée pour localiser une défaillance.

Pour une chaîne plus détaillée, vous pouvez intégrer un outil de traçage ; les plateformes d'observabilité prises en charge dépendent de la documentation de la version actuelle. Quel que soit l'outil, enregistrez de façon homogène le nom du modèle, l'identifiant de requête, la durée, les tokens d'entrée et de sortie, le code d'erreur et le nombre de tentatives. Les 429, les délais d'attente et les changements de modèle peuvent ainsi être détectés par tendance, au lieu d'attendre une réclamation utilisateur.

8. Un ordre de diagnostic réutilisable

  1. Appelez directement l'API de l'application Dify avec curl -i et notez le code HTTP et le corps de réponse.
  2. Vérifiez que l'URL de base, le point de terminaison et le type d'application correspondent, pour écarter le 404.
  3. Vérifiez que la clé d'application et la clé du fournisseur ne sont pas mélangées, pour écarter le 401.
  4. Testez séparément le fournisseur de modèles dans l'interface Dify pour confirmer que l'amont fonctionne.
  5. Ouvrez l'historique d'exécution du workflow, trouvez le premier nœud en échec et examinez ses entrées et sorties.
  6. Contrôlez le contexte, la limite de sortie et les paramètres de rappel de la base de connaissances, pour écarter un problème de tokens.
  7. Consultez les journaux de l'amont et de la passerelle pour confirmer un 429, un délai d'attente ou un quota.
  8. Après correction, rejouez le même lot de requêtes et surveillez le taux d'erreur pendant un certain temps.

Commande de reproduction minimale ; -i permet de voir à la fois le code de statut et les en-têtes :

export DIFY_API_KEY="app-votre-cle-application"

curl -i -sS "https://api.dify.ai/v1/chat-messages" \
  -H "Authorization: Bearer $DIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Réponds uniquement OK",
    "response_mode": "blocking",
    "user": "diag-001"
  }'

En auto-hébergement, remplacez par l'adresse de votre instance ; pour une application de workflow, utilisez /v1/workflows/run et les paramètres correspondants. Faites d'abord passer une requête minimale, puis ajoutez progressivement l'historique, la base de connaissances et les outils : vous localiserez rapidement la couche fautive.

Questions fréquentes

Le test du modèle réussit dans Dify, mais l'API de l'application renvoie 401 ?

Les deux n'utilisent pas la même clé. Le test du modèle emploie la clé du fournisseur, l'API de l'application emploie sa propre clé. Vérifiez que l'en-tête contient bien Bearer suivi de la clé d'application, et que cette clé appartient à l'application et à l'espace de travail courants.

L'adresse semble correcte, pourquoi un 404 ?

Les causes courantes sont un point de terminaison incompatible avec le type d'application, ou un chemin en trop ou manquant dans l'URL de base. Dify Cloud utilise https://api.dify.ai/v1, l'auto-hébergement le domaine de l'instance ; les points de terminaison diffèrent selon le type d'application, vérifiez-les en conséquence.

Combien de tentatives pour un 429 ?

Il n'existe pas de nombre universel. Fixez un nombre maximal de tentatives et une durée d'attente totale, utilisez un backoff exponentiel avec gigue aléatoire, et ne réessayez que les 429 et les 5xx. Si le problème persiste, réduisez la concurrence ou le quota plutôt que de réessayer sans fin.

Un nœud de workflow échoue : peut-on laisser le flux continuer ?

Vous pouvez évaluer une gestion d'erreur au niveau du nœud : nouvelle tentative, valeur par défaut ou branche d'exception. Réservez-la aux nœuds dégradables ; une erreur d'authentification ou de paramètre doit rester visible, sans être absorbée par une valeur par défaut.

Que faire si les journaux ne montrent pas l'erreur brute de l'amont ?

Vérifiez d'abord si l'historique d'exécution de Dify contient une erreur au niveau du nœud, puis consultez la console du fournisseur et les journaux de la passerelle. Si l'amont ne renvoie qu'une erreur générique, appelez directement son interface avec la même clé et le même nom de modèle : vous obtiendrez généralement plus d'informations.

Pour aller plus loin

Le diagnostic des erreurs Dify repose sur la séparation des couches : distinguer l'API d'application, la configuration Dify et le modèle amont, puis localiser point par point selon le code de statut et l'erreur du nœud. Pour un point d'entrée modèle unifié et des journaux d'appel centralisés, vous pouvez d'abord créer un compte ZSQH AI Gateway ; les modèles et les tarifs sont indiqués sur la page tarifs des modèles.

Lectures associées :