Fehlerbehandlung in n8n: Retries, Dead-Letter-Queues und Alarme

Der erste Workflow ist in einer Stunde gebaut. Die Rechnung kommt per Mail, Claude liest Betrag und Lieferant aus, ein Datensatz landet im ERP. Der hundertste Workflow entscheidet, ob Automatisierung in Ihrem Unternehmen funktioniert. Denn irgendwann ändert ein Lieferant sein PDF-Layout, die ERP-API antwortet mit 503, und niemand merkt es. Hier zeigen wir, wie wir Fehlerbehandlung in n8n aufbauen, damit Fehler sichtbar werden, statt still zu verschwinden.

Ein stiller Fehler ist schlimmer als kein Workflow

Ohne Automatisierung buchen Mitarbeiter Rechnungen von Hand. Das ist langsam, aber jemand sieht jede Rechnung. Mit einem Workflow, der seit drei Wochen stillschweigend abbricht, sieht niemand mehr etwas, und alle verlassen sich darauf. Der Schaden zeigt sich erst bei der Mahnung des Lieferanten oder im Monatsabschluss.

Daraus folgt die Grundregel: Jeder Fehler muss dort ankommen, wo ein Mensch ihn sieht. Alles Weitere in diesem Artikel ist Technik, um diese Regel umzusetzen.

Error-Workflows: Das Fundament

n8n kann für jeden Workflow einen Error-Workflow hinterlegen. Schlägt eine Execution fehl, startet dieser über den Error Trigger und bekommt Workflow-Name, Execution-ID, den fehlgeschlagenen Node und die Fehlermeldung.

Unser Standard ist ein zentraler Error-Workflow für die gesamte Instanz, der

• die Fehlerdaten in eine Tabelle schreibt,
• anhand der Workflow-Tags entscheidet, wer benachrichtigt wird,
• eine Nachricht nach Slack oder Teams schickt, mit Link zur Execution.

Der Error-Workflow ist Pflicht, nicht Option. Bei uns geht kein Workflow auf Produktion, ohne dass er eingetragen ist. Das prüfen wir per Skript über die n8n-API. Zwei Dinge überraschen im Review: Der Error-Workflow greift nur bei automatischen Ausführungen, nicht beim manuellen Test. Und er greift nicht, wenn ein Node per "Continue on Fail" den Fehler schluckt. Dazu gleich mehr.

Retries: Richtig eingestellt, nicht überall

Jeder Node hat in den Einstellungen "Retry On Fail" mit Anzahl und Wartezeit. Das hilft bei vorübergehenden Fehlern: Timeout, 429, 503. Es hilft nicht bei einem falschen API-Key oder einem fehlenden Pflichtfeld. Dort sorgt ein Retry nur dafür, dass der Fehler dreimal so lange braucht.

Unsere Regeln:

• Retry bei HTTP-Nodes gegen externe APIs: drei Versuche mit Wartezeit. Die Wartezeit in n8n ist auf wenige Sekunden begrenzt. Ist eine API eine halbe Stunde weg, brauchen Sie das Dead-Letter-Pattern weiter unten.
• Kein Retry bei Nodes, die etwas schreiben, solange der Schreibvorgang nicht idempotent ist. Sonst steht die Rechnung zweimal im ERP.
• "Continue using error output" nur dort, wo Sie den Fehlerausgang auch verdrahten. Ein Node mit "Continue" und ohne verbundenen Fehlerausgang ist die häufigste Quelle stiller Fehler, die wir in Reviews finden.
• Bei Claude-Aufrufen ist ein Retry bei Rate Limits sinnvoll. Prüfen Sie aber auch die Antwort inhaltlich. Ein JSON, dem ein Feld fehlt, ist ebenfalls ein Fehler, nur ohne Statuscode.

Idempotenz: Retries ohne Doppelbuchungen

Retries sind nur dann ungefährlich, wenn jeder Schritt mehrfach laufen darf, ohne doppelte Effekte. Konkret heißt das:

• Jedes Item bekommt einen fachlichen Schlüssel: Rechnungsnummer plus Lieferant, Bestell-ID oder Message-ID der Mail.
• Vor dem Schreiben prüfen, ob der Datensatz mit diesem Schlüssel schon existiert. Dann aktualisieren oder überspringen, nicht neu anlegen.
• Wo die Ziel-API es unterstützt, Idempotency-Keys mitschicken. Zahlungs-APIs können das fast alle.
• Externe Nebenwirkungen wie E-Mails ans Ende des Workflows, nach allen Schreibvorgängen. Und in der Tabelle festhalten, dass die Mail raus ist.

Ein idempotenter Workflow darf nach einem Fehler einfach neu gestartet werden. "Retry" in der Oberfläche ist dann eine sichere Aktion, kein Risiko.

Dead-Letter-Pattern: Fehler parken statt verlieren

Manche Fehler lösen sich nicht durch Retry. Das PDF ist nicht lesbar, der Kunde fehlt im ERP, die API ist stundenlang weg. Diese Fälle gehören in eine Dead-Letter-Queue: einen Ort, an dem fehlgeschlagene Items liegen, bis jemand oder etwas sie wieder aufnimmt.

Zwei Umsetzungen haben sich bewährt:

• Eine Tabelle in Postgres mit Workflow, Schlüssel, Payload, Fehlermeldung, Versuchen und Status. Der Error-Workflow schreibt hinein. Ein geplanter Workflow liest stündlich alle offenen Einträge und versucht sie erneut, bis zu einer Obergrenze. Danach Status "manual" und eine Nachricht an die Fachabteilung.
• Eine SQS-Queue auf AWS mit angeschlossener Dead-Letter-Queue, wenn Ihre Workflows ohnehin über Queues angestoßen werden. SQS übernimmt Sichtbarkeits-Timeout und das Zählen der Versuche. n8n liest mit dem SQS-Node.

Die Tabelle sieht bei uns so aus:

CREATE TABLE failed_items (
  id          bigserial PRIMARY KEY,
  workflow    text NOT NULL,
  item_key    text NOT NULL,
  payload     jsonb NOT NULL,
  error       text,
  attempts    int DEFAULT 0,
  status      text DEFAULT 'open',
  created_at  timestamptz DEFAULT now(),
  UNIQUE (workflow, item_key)
);

Sie ist gleichzeitig Ihr Report: Welche Workflows fallen wie oft aus, und woran. Das ist die Grundlage für die Entscheidung, welchen Workflow Sie als Nächstes härten.

Alarme mit Verantwortlichen und klaren Namen

Ein Alarm ohne Empfänger ist eine Logzeile. Deshalb:

• Jeder Workflow hat einen Owner. Der Name steht in der Beschreibung des Workflows und in einer Übersicht, die die Fachabteilung kennt.
• Ein Kanal pro Fachbereich, nicht ein Kanal für alles. Der Finance-Kanal geht an die Buchhaltung und den IT-Owner. Ein Sammelkanal ist nach zwei Wochen stummgeschaltet.
• Die Nachricht enthält Workflow, Schlüssel des betroffenen Items, Fehlermeldung in einem Satz, Link zur Execution, und was zu tun ist. "Lieferant Müller fehlt im ERP, bitte anlegen" ist hilfreich. "Error in node HTTP Request" ist es nicht.
• Zusätzlich ein täglicher Digest mit Anzahl der Executions, Fehlern und offenen Dead-Letter-Einträgen. Bleibt der Digest aus, ist das selbst ein Alarm, denn dann steht die Instanz.

Namenskonventionen gehören dazu, weil sie Alarme lesbar machen. Bewährt hat sich das Muster [Bereich] Was passiert, etwa [Finance] Eingangsrechnung nach ERP oder [HR] Onboarding Zugänge anlegen. Dazu Tags für Owner und Kritikalität. Wer um drei Uhr nachts eine Nachricht liest, soll sofort wissen, ob sie bis morgen warten kann.

Fazit

Der erste Workflow läuft in einer Stunde. Ob der hundertste noch läuft, entscheiden Error-Workflows, Retries mit Idempotenz, ein Ort für fehlgeschlagene Items und Alarme mit Owner. Das ist weniger Arbeit, als es klingt, wenn Sie es von Anfang an mitnehmen. Wenn Sie Ihre n8n-Workflows auf Produktionsreife bringen möchten, buchen Sie ein kostenloses 30-minütiges Kennenlerngespräch.