Dify kennt zwei Fehlerebenen: Fehler beim Aufruf der App-API und Fehler, die Dify beim Aufruf des Modellanbieters erhält. Beide Ebenen können 401, 404 oder 429 zurückgeben, doch die Ursachen liegen an völlig unterschiedlichen Stellen. Wer nur auf den Statuscode starrt, ändert die Konfiguration leicht auf der falschen Ebene immer wieder.

Dieser Beitrag gliedert häufige Probleme in sechs Ebenen – Authentifizierung, Adresse, Rate Limits, Workflow, Kontext und Logs – und nennt minimale Reproduktionsbefehle sowie eine feste Prüfreihenfolge. Fehlercodes, Limits und Bezeichnungen in der Oberfläche richten sich nach der offiziellen Dokumentation von Dify und den Modellanbietern.

Hinweis: Dify ist eine Marke des jeweiligen Inhabers. Dieser Beitrag steht in keiner Zugehörigkeitsbeziehung zu den genannten Anbietern; weitere genannte Produktnamen gehören ihren jeweiligen Inhabern. Beispielhaft wird der übliche Versionsstand von Oktober 2026 beschrieben.

1. Zuerst drei Ebenen trennen, nicht von vorn raten

Eine Anfrage durchläuft mindestens drei Ebenen: Client, Dify-App-API und Modellanbieter, dazwischen kann ein Gateway liegen. Ein 401 kann zwischen Client und Dify oder zwischen Dify und Upstream entstehen; ein 404 kann ein falscher Pfad oder ein falscher Modellname sein; 429 kommt meist vom Upstream.

Lesen Sie zuerst message, code und die Request-ID im Antwortkörper, bevor Sie entscheiden, welche Ebene Sie prüfen. Praktische Faustregel: Rufen Sie die App-API direkt mit curl auf. Kommt derselbe Fehler, liegt das Problem in der Dify-Konfiguration oder beim Upstream. Funktioniert curl, während der Anwendungscode scheitert, liegt es am Client oder am Netzwerk.

2. 401 und 403: zwei Key-Systeme nicht vermischen

Dify verwendet zwei Arten von Zugangsdaten: Der App-API-Key ruft die Dify-App auf, der Modellanbieter-Key wird von Dify für den Upstream-Aufruf verwendet. Ersterer gehört in den Header Authorization: Bearer ..., letzterer in die Einstellungen des Modellanbieters. Die Verwechslung ist die häufigste Ursache für 401.

Häufige Ursachen:

  • Im Header fehlt Bearer, oder der Key enthält führende bzw. nachfolgende Leerzeichen, Zeilenumbrüche oder Anführungszeichen.
  • Es wurde der Key einer anderen App verwendet. App-Keys werden in der Regel pro App erstellt und gelten nicht app-übergreifend.
  • Der Key wurde gelöscht oder rotiert, oder der Workspace hat keinen Zugriff auf die App.
  • Der Modellanbieter-Key ist abgelaufen, das Guthaben reicht nicht, er wurde widerrufen, oder beim Kopieren fehlen Zeichen.
  • Reverse Proxy, Gateway oder Frontend filtern den Authorization-Header heraus.

403 hängt meist mit Berechtigungen zusammen: eine zu niedrige Workspace-Rolle, ein nicht freigegebenes Modell beim Anbieter oder ein eingeschränktes Upstream-Konto. Klären Sie zuerst, wer wen aufruft, und testen Sie dann mit einem anderen Key.

3. 404 und „Modell nicht gefunden“: Adresse und Namen getrennt prüfen

Beim Aufruf der Dify-App-API gibt es drei typische 404-Ursachen:

  1. Falsche Base URL: Die App-API von Dify Cloud liegt unter https://api.dify.ai/v1; bei Selbsthosting verwenden Sie Ihre eigene Domain und Ihren Pfad. Fehlt /v1 oder wird der vollständige Endpunktpfad zusätzlich angehängt, folgt ein 404.
  2. Endpunkt passt nicht zum App-Typ: Chat-Apps nutzen chat-messages, Workflow-Apps workflows/run, Textgenerierungs-Apps completion-messages. Bei falschem Endpunkt führt selbst ein korrekter Key zu 404 oder 400.
  3. Reverse Proxy verändert den Pfad: Nginx-Unterpfade, abschließende Schrägstriche und URL-Rewrite-Regeln können Anfragen auf nicht existierende Routen leiten.

Stammt der Fehler vom Modellanbieter, erscheinen häufig „model not found“, „model does not exist“ oder „invalid model“. Prüfen Sie, ob die Modell-ID exakt dem aktuell gelisteten Namen des Anbieters entspricht – einschließlich Groß- und Kleinschreibung, Datums-Suffix und Alias. Stellen Sie außerdem sicher, dass das Modell in Dify aktiviert ist und die Plugin-Version es unterstützt. Auch ein abgekündigtes oder umbenanntes Modell macht die bisherige Konfiguration ungültig.

4. 429: Rate Limits, Parallelität und Kontingente

429 kommt in der Regel nicht von Dify, sondern vom Upstream-Modellservice oder Gateway und bedeutet „zu viele Anfragen“. Auslöser können Anfragen pro Minute, Token pro Minute, Parallelität oder das Kontingent des Kontos sein. Batch-Aufgaben, Schleifenknoten und viele gleichzeitige Nutzer treiben die momentane Parallelität am schnellsten hoch.

Vorgehen:

  • Prüfen Sie zuerst Antwort-Header und Fehlermeldung: Handelt es sich um Anfragefrequenz, Token-Rate oder Parallelitätslimit?
  • Senken Sie die Parallelität im Client und geben Sie Batch-Aufgaben eine Warteschlange, statt alles auf einmal abzuschicken.
  • Wiederholen Sie nur 429 und 5xx, mit exponentiellem Backoff plus Jitter und einer Obergrenze für Versuche.
  • Achten Sie bei Workflow-Wiederholungen auf Idempotenz: Derselbe Geschäftsvorgang kann Knoten mehrfach ausführen; besser einen Deduplizierungsschlüssel in der Anwendungsebene ergänzen.
  • Bei dauerhaft häufigen Auslösern sollten Sie Apps, Keys oder Projekte aufteilen oder die Aufrufzeiten anpassen.

Blindes Wiederholen macht aus einem Rate Limit einen Ausfall. Klären Sie vor jedem Retry, ob die Anfrage bereits Nebenwirkungen erzeugt hat.

5. Workflow-Fehler: bei den Ein- und Ausgaben der Knoten beginnen

Scheitert ein Workflow als Ganzes, lässt sich meist ein einzelner Knoten identifizieren. Häufige Typen:

Symptom Häufige Ursache Zuerst prüfen
Variablenreferenz leer Vorgelagerter Knoten gibt die Variable nicht aus, oder der Name ist falsch geschrieben Ausgabestruktur des Knotens und Variablenauswahl
Typ passt nicht Ein String wird als Array oder Objekt verwendet Rückgabetyp des Vorgängers und Konvertierungsknoten
Fehler im Code-Knoten Syntax, Abhängigkeiten, Timeout oder falsche Rückgabestruktur Laufzeitlog und Konventionen des Code-Knotens
HTTP-Knoten schlägt fehl Kein 2xx, Authentifizierungsfehler, Timeout, Zertifikatsproblem Statuscode, Header, Logs des Zielservices
LLM-Ausgabe nicht parsebar Modell liefert nicht das erwartete JSON Prompt-Einschränkungen und Fehlertoleranz beim Parsen
Wissensabruf leer Index unvollständig, Schwellenwert zu hoch, Query-Umschreibung fehlgeschlagen Status der Wissensbasis und Recall-Parameter
Iterationsknoten schlägt fehl Eingabe ist kein Array, oder der Unterfluss referenziert falsch Iterationseingabe und Struktur des Einzelelements

Dify unterstützt Fehlerbehandlung auf Knotenebene, etwa Wiederholungsversuche, Standardwerte oder Ausnahmezweige. Für kritische Knoten ist eine Absicherung kontrollierbarer als ein komplett fehlschlagender Ablauf. Standardwerte dürfen jedoch keine Konfigurationsfehler verdecken, sonst treten sie erst stromabwärts zutage.

6. Kontext- und Token-Limits

Kontextfehler erscheinen meist als 400 mit „context length exceeded“, „maximum context“ oder „token limit“. Die Ursache ist nicht „das Modell taugt nicht“, sondern die Summe aus Eingabe und Ausgabe überschreitet den erlaubten Bereich. Sie umfasst Systemprompt, Gesprächsverlauf, abgerufene Wissensfragmente, Nutzereingabe und reservierte Ausgabe.

Reduzieren Sie bei der Diagnose Punkt für Punkt:

  • Begrenzen Sie die Zahl der Verlaufsturns oder fassen Sie zuerst zusammen.
  • Verringern Sie die Zahl der Wissensabrufe, aktivieren Sie Reranking und entfernen Sie irrelevante Fragmente.
  • Passen Sie die Dokumentaufteilung an, damit einzelne Blöcke nicht zu lang werden.
  • Legen Sie die maximale Ausgabe-Tokenzahl separat fest und lassen Sie Spielraum für die Eingabe.
  • Schätzen Sie Token auf Anwendungsseite und kürzen oder leiten Sie vor dem Limit auf ein Modell mit längerem Kontext um.

Die in Dify konfigurierte Kontextlänge muss dem tatsächlich unterstützten Wert des Anbieters entsprechen. Ein größerer Wert als beim Upstream führt zu Ablehnung; ein zu kleiner Wert schneidet lange Dokumente vorzeitig ab.

7. Logs und Tracing: eine Anfrage durchgängig verfolgen

Die Fehlersuche darf nicht bei der letzten Fehlermeldung enden. Halten Sie mindestens vier Informationsarten fest: Dify-App-Logs und Workflow-Aufzeichnungen, Logs des Modellanbieters, Gateway-Request-Logs sowie Nutzer- und Request-IDs auf Anwendungsseite. Die Laufzeitaufzeichnung von Dify zeigt Ein- und Ausgaben sowie Dauer jedes Knotens und ist der erste Einstiegspunkt bei Fehlern.

Für detailliertere Ketten können Sie Tracing-Tools anbinden; welche Observability-Plattformen unterstützt werden, richtet sich nach der Dokumentation der aktuellen Version. Unabhängig vom Tool sollten Modellname, Request-ID, Dauer, Eingabe- und Ausgabe-Token, Fehlercode und Anzahl der Wiederholungen einheitlich erfasst werden. So werden 429, Timeouts und Modelländerungen als Trend sichtbar, statt erst durch Nutzerbeschwerden aufzufallen.

8. Eine wiederverwendbare Prüfreihenfolge

  1. Rufen Sie die Dify-App-API direkt mit curl -i auf und protokollieren Sie HTTP-Status und Antwortkörper.
  2. Prüfen Sie Base URL, Endpunkt und App-Typ auf Übereinstimmung, um 404 auszuschließen.
  3. Stellen Sie sicher, dass App-Key und Modellanbieter-Key nicht vermischt sind, um 401 auszuschließen.
  4. Testen Sie den Modellanbieter in der Dify-Oberfläche separat und bestätigen Sie die Erreichbarkeit des Upstreams.
  5. Öffnen Sie die Workflow-Aufzeichnung, suchen Sie den ersten fehlgeschlagenen Knoten und prüfen Sie Ein- und Ausgaben.
  6. Prüfen Sie Kontext, Ausgabelimit und Recall-Parameter der Wissensbasis, um Token-Probleme auszuschließen.
  7. Sehen Sie Upstream- und Gateway-Logs ein und bestätigen Sie 429, Timeout oder Kontingentgrenzen.
  8. Testen Sie nach der Korrektur dieselbe Anfragecharge erneut und beobachten Sie die Fehlerrate über einen Zeitraum.

Der minimale Reproduktionsbefehl sieht so aus; -i zeigt Statuscode und Antwort-Header gemeinsam:

export DIFY_API_KEY="app-Ihr-App-Key"

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

Bei Selbsthosting verwenden Sie die Adresse Ihrer Instanz; für Workflow-Apps nutzen Sie /v1/workflows/run mit den passenden Parametern. Bringen Sie zuerst eine minimale Anfrage zum Laufen und ergänzen Sie schrittweise Verlauf, Wissensbasis und Tools – so lässt sich die fehlerhafte Ebene schnell eingrenzen.

Häufige Fragen

Der Modelltest in Dify gelingt, die App-API liefert aber 401?

Beide verwenden unterschiedliche Keys. Der Modelltest nutzt den Anbieter-Key, die App-API den Key der App selbst. Prüfen Sie, ob der Header aus Bearer und dem App-Key besteht, und ob der Key zur aktuellen App und zum Workspace gehört.

Die Adresse sieht richtig aus – warum trotzdem 404?

Häufig passen Endpunkt und App-Typ nicht zusammen, oder die Base URL enthält einen Pfad zu viel bzw. zu wenig. Dify Cloud verwendet https://api.dify.ai/v1, Selbsthosting die Domain der Instanz; verschiedene App-Typen haben unterschiedliche Endpunkte. Prüfen Sie beides getrennt.

Wie viele Wiederholungen bei 429 sind sinnvoll?

Eine pauschale Zahl gibt es nicht. Legen Sie eine maximale Anzahl und eine Gesamtwartezeit fest, nutzen Sie exponentielles Backoff mit Jitter und wiederholen Sie nur 429 und 5xx. Bei wiederholtem Auftreten sollten Sie Parallelität oder Kontingent senken, nicht endlos wiederholen.

Kann ein Workflow weiterlaufen, wenn ein Knoten fehlschlägt?

Prüfen Sie die Fehlerbehandlung auf Knotenebene: Wiederholung, Standardwert oder Ausnahmezweig. Verwenden Sie sie nur für Knoten, die sich gefahrlos degradieren lassen; Authentifizierungs- und Parameterfehler sollten sichtbar bleiben und nicht durch Standardwerte verschluckt werden.

Was tun, wenn im Log der ursprüngliche Upstream-Fehler fehlt?

Prüfen Sie zuerst, ob die Dify-Aufzeichnung einen Knotenfehler enthält, und sehen Sie dann im Anbieter-Konsolen- und Gateway-Log nach. Liefert der Upstream nur eine allgemeine Meldung, rufen Sie seine Schnittstelle mit demselben Key und Modellnamen direkt per curl auf – meist ist die Antwort dort ausführlicher.

Nächster Schritt

Der Kern der Dify-Fehlerdiagnose ist die Trennung der Ebenen: Zuerst klären, ob App-API, Dify-Konfiguration oder Upstream-Modell betroffen ist, dann anhand von Statuscode und Knotenfehlern eingrenzen. Wenn Sie einen einheitlichen Modelleingang und zentrale Aufruflogs benötigen, können Sie sich zunächst im ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.

Weiterführende Beiträge: