Wenn ein n8n-Workflow scheitert, zeigt die Leinwand meist nur eine rote Zeile. Die wirklich nützlichen Informationen stecken im Ausführungsprotokoll: HTTP-Statuscode, vom Upstream zurückgegebener Error-Code und die Adresse, an die die Anfrage tatsächlich ging. Mit diesen drei Angaben lassen sich die meisten Fehler in wenigen Minuten eingrenzen.

Dieser Artikel trennt die Fehler nach Typ: 401 und 403 betreffen Zugangsdaten und Rechte, 404 meist Base URL oder Modellname, 429 Rate-Limits und Kontingente; bei Node-Timeouts und Workflow-Fehlern sind Konfiguration und Laufzeitumgebung zu prüfen, zuletzt JSON-Parsing-Fehler. Am Ende steht eine feste Prüfreihenfolge, die Teams als eigenes Runbook übernehmen können.

Hinweis: n8n und OpenAI sind Marken der jeweiligen Rechteinhaber; dieser Artikel steht in keiner Zugehörigkeit zu den genannten Anbietern. Modellnamen und Preise richten sich nach den Modellpreisen, Node-Felder nach der tatsächlich verwendeten Version.

1. Zuerst das Ausführungsprotokoll lesen, nicht raten

Links unter Executions den Filter Failed wählen, die fehlgeschlagene Ausführung öffnen und Node für Node Eingabe, Ausgabe und Fehlerdetails prüfen. Vier Angaben sollten festgehalten werden: Node-Name, HTTP-Statuscode, Error-Code des Upstreams und Request-ID, falls vorhanden. Sie entscheiden, ob das Problem in der n8n-Konfiguration, der Netzwerkstrecke oder beim Upstream liegt.

Eine grobe Einordnung nach Statuscode:

Statuscode Häufige Bedeutung Zuerst prüfen
401 Nicht authentifiziert oder Key ungültig Ob Zugangsdaten ausgewählt und der Key gültig ist
403 Authentifiziert, aber ohne Recht Modellrechte, IP-Whitelist
404 Adresse oder Modell existiert nicht Base-URL-Pfad, Schreibweise des Modellnamens
429 Rate-Limit oder Kontingent erschöpft Parallelität, Retry-Strategie, Kontostand
400 Anfrageparameter unzulässig Feldnamen, Kontextlänge, Nachrichtenformat
5xx Vorübergehende Störung beim Upstream Später erneut versuchen, Statusseite prüfen

2. 401: Auch ein korrekter Key kann scheitern

401 bedeutet nicht immer „Key falsch eingetragen“. Weitere häufige Ursachen: Die Zugangsdaten wurden angelegt, aber im Workflow-Node nicht ausgewählt; beim Kopieren sind Leerzeichen oder Zeilenumbrüche hineingeraten; ein Test-Key wurde deaktiviert; im Team teilen sich mehrere Personen eine Instanz und der Node referenziert einen anderen Zugangsdatensatz; eine selbst betriebene Instanz hat N8N_ENCRYPTION_KEY gewechselt, sodass alte Zugangsdaten nicht mehr entschlüsselt werden können.

Die Reihenfolge ist einfach: Zugangsdaten neu auswählen, Key neu einfügen, speichern und den Node einzeln ausführen. Bleibt der Fehler, auf einer Maschine mit vergleichbarer Netzwerkumgebung wie n8n einen curl-Aufruf starten:

curl -i https://ihre-gateway-adresse/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"IhrModellname","messages":[{"role":"user","content":"Antworte nur mit OK"}]}'

Gelingt curl, scheitert n8n, liegt es an Zugangsdaten oder Node-Konfiguration. Scheitern beide, liegt es an Key, Gateway oder Netzwerk. Keys gehören nicht in Code-Nodes, Workflow-JSON oder Notizfelder, da diese leicht exportiert und geteilt werden.

3. 404: Base URL und Modellname je zur Hälfte

Bei OpenAI-Zugangsdaten endet die Base URL üblicherweise bei /v1, den Rest /chat/completions hängt der Node selbst an. Wird ein vollständiger Pfad zusätzlich eingetragen, entstehen Adressen wie /v1/chat/completions/chat/completions und der Aufruf liefert 404. Umgekehrt benötigt ein HTTP-Request-Node die vollständige URL und nicht nur die Domain.

Die andere Hälfte der 404-Fälle betrifft den Modellnamen. OpenAI-kompatible Dienste melden ein unbekanntes Modell oft als model_not_found, teils mit 404, teils in einer 400-Antwort verpackt. Drei Dinge abgleichen: Groß- und Kleinschreibung, vorhandenes Datumssuffix und die Frage, ob das Gateway einen Alias oder den ursprünglichen Upstream-Namen erwartet. Am zuverlässigsten ist ein Aufruf von /v1/models; nur Namen aus dieser Liste verwenden.

Weitere Details: Ein zusätzlicher Schrägstrich am Ende der Base URL kann doppelte Schrägstriche erzeugen; liegt das Gateway unter einem Unterpfad eines Reverse Proxy, darf das Präfix nicht fehlen; nach einem Wechsel zwischen Test- und Produktionsumgebung wurde die Adresse nicht mitgeändert.

4. 429: Rate-Limits nicht nur mit Retries aussitzen

429 zeigt an, dass Anfragen begrenzt werden. Drei Auslöser sind üblich: zu viele Anfragen oder Tokens pro Minute, zu hohe Parallelität, aufgebrauchtes Kontingent oder Guthaben. Enthält der Antwort-Header einen Retry-After-Wert, sollte dieser abgewartet werden, statt sofort erneut zu senden.

In den Node-Einstellungen von n8n lässt sich Retry On Fail aktivieren, mit zwei bis drei maximalen Versuchen und ansteigender Wartezeit. Retries fangen jedoch nur kurze Schwankungen ab und lösen keine dauerhafte Überschreitung. Bei Stapelaufgaben die Parallelität senken, mit Split In Batches oder Loop Over Items in Portionen arbeiten und zwischen den Portionen Pausen lassen; Zeitpläne möglichst entzerren; beim Debuggen nicht direkt den gesamten Datenbestand verarbeiten.

5. Node-Timeouts und fehlgeschlagene Workflows

Bei Timeouts zuerst die Ebene bestimmen: Timeout des HTTP-Request-Nodes, Timeout auf Workflow-Ebene, Timeout von Reverse Proxy oder Load Balancer, Generierungsdauer des Upstream-Modells. Erreicht eine Ebene zuerst die Grenze, scheitert die Ausführung; die Formulierungen in der Fehlermeldung unterscheiden sich meist.

Lange Textgenerierung überschreitet leicht die Standardgrenzen. Der Node-Timeout kann moderat erhöht werden, parallel sollten Eingabe komprimiert, maximale Ausgabelänge begrenzt und Aufgaben aufgeteilt werden. Der Workflow darf nicht unbegrenzt warten, und ein sehr hoher Timeout blockiert bei Störungen lange Ausführungsplätze. Bei selbst betriebenen Instanzen außerdem prüfen, ob Prozesse neu gestartet wurden und Worker im Queue-Modus online sind.

Auch die Fehlerstrategie pro Node gehört zur Konfiguration: Stapelaufgaben mit On Error weiterlaufen lassen und fehlerhafte Elemente behalten; kritische Schreib-Nodes stoppen den Workflow. Zusätzlich einen Error Workflow einrichten, der Ausführungs-ID, Node-Name und Eingabezusammenfassung in Gruppenchat oder E-Mail sendet. Fehler sind nicht das Problem – fehlende Aufzeichnungen sind es.

6. JSON-Parsing-Fehler: Die Modellausgabe ist kein JSON

Typische Meldungen sind „JSON parameter needs to be valid JSON“ oder eine Ausnahme bei JSON.parse im Code-Node. Häufig legt das Modell Erklärtext oder Markdown-Codezäune um das JSON, oder Feldtypen weichen von der Vereinbarung ab.

Zuerst beim Upstream ansetzen: Der Prompt verlangt ausdrücklich „nur JSON, kein Codeblock“, Felder und Typen sind klar benannt; unterstützt Gateway oder Modell strukturierte Ausgaben, diese bevorzugen. Downstream trotzdem defensiv parsen, etwa im Code-Node:

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 } }];
}

Parse-Fehler nicht stillschweigend verwerfen, sondern den Originaltext in eine Fehlertabelle schreiben und einige Fälle manuell prüfen. Das deckt meist Probleme im Prompt oder bei den Fähigkeiten des Modells auf.

7. Eine wiederverwendbare Prüfreihenfolge

  1. Ausmaß bestimmen: Scheitert ein einzelner Datensatz, eine ganze Charge oder der gesamte Workflow?
  2. Im selben Netzwerk wie n8n mit curl reproduzieren, um Störungen durch die Node-Konfiguration auszuschließen.
  3. Tatsächlich gesendete URL, Header und Body mit der n8n-Konfiguration vergleichen, besonders die Base-URL-Zusammensetzung.
  4. /v1/models abfragen und Modellnamen samt Schreibweise und Suffix bestätigen.
  5. Statuscode und Error-Code notieren: 401, 403 und 404 nicht wiederholen; nur 429, 5xx und Timeouts sind Retry-Kandidaten.
  6. Timeout, Parallelität und Chargengröße prüfen und erst dann Retry-Parameter ändern.
  7. Das Ergebnis mit Fehlerbeispielen und Korrekturmaßnahmen ins Team-Runbook schreiben.

Häufige Fragen

n8n meldet 401, curl funktioniert aber – woran liegt es?

Zuerst prüfen, ob der Node die falschen Zugangsdaten referenziert, ob der Key Leerzeichen oder Zeilenumbrüche enthält und ob die Instanz den Verschlüsselungsschlüssel gewechselt hat. Alternativ im HTTP-Request-Node den Authorization-Header manuell setzen und vergleichen, ob das Problem bei der Auswertung der Zugangsdaten oder beim Aufbau der Anfrage liegt.

Ist ein 404 immer eine falsche Base URL?

Nein. Ein zusätzlicher Pfad, ein fehlendes /v1 oder ein verlorenes Reverse-Proxy-Präfix erzeugen ebenfalls 404; auch ein unbekannter Modellname kann 404 zurückgeben. Zuerst mit /v1/models prüfen, ob das Modell existiert, dann die Adressebenen kontrollieren.

Wie viele Retries sind bei 429 sinnvoll?

Üblicherweise zwei bis drei, mit ansteigender Wartezeit und Beachtung von Retry-After. Ein dauerhafter 429 zeigt, dass Parallelität oder Kontingent überschritten sind; weitere Versuche verstärken die Überlast. Stattdessen Chargengröße senken oder Ausführungszeiten entzerren.

Der Workflow gilt als erfolgreich, das Ergebnis ist aber leer – wie prüfen?

Das Ausführungsprotokoll Node für Node öffnen und kontrollieren, ob die Modellausgabe durch eine spätere Feldzuordnung überschrieben wurde; prüfen, ob die Ausgabe abgeschnitten wurde oder eine Inhaltsfilterung griff; anschließend bestätigen, dass die im Ausdruck referenzierten Feldnamen zur tatsächlichen Struktur des vorherigen Schritts passen.

Welche Netzwerkprobleme sind bei selbst betriebenem n8n zu beachten?

Sicherstellen, dass Container oder Host den Gateway-Domainnamen auflösen und erreichen können; Proxy-Umgebungsvariablen, ausgehende Firewall-Regeln und IP-Whitelists prüfen. Zeitgesteuerte und manuelle Ausführungen können über unterschiedliche Instanzen laufen, daher beide Umgebungen testen.

Nächste Schritte

Die allgemeine Regel lautet: erst Belege sammeln, dann die Konfiguration ändern; erst Adresse und Zugangsdaten korrigieren, dann über Retries und Timeouts sprechen. Für einen einheitlichen OpenAI-kompatiblen Zugang, separate virtuelle Keys und Verbrauchsprotokolle können Sie sich im ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.

Weiterlesen: