n8n-Fehlerbehandlung: Wiederholungen ohne doppelte Aktionen

Die Tabelle unterscheidet diese Fehlersituationen und die jeweils sinnvolle Reaktion.

HTTP-Status. Ein HTTP-Status hilft bei der Einordnung, genügt aber nicht allein. Lesen Sie die Fehlermeldung und den Vertrag der jeweiligen API. Ein Konflikt kann beispielsweise eine bereits existierende Ressource oder eine unzulässige Zustandsänderung bedeuten. Daraus folgen unterschiedliche Maßnahmen.

Geschäftliche Folge. Richten Sie die Einordnung an der geschäftlichen Folge aus. Ein fehlgeschlagener Lesezugriff lässt das Ziel in der Regel unverändert. Ein Schreibzugriff mit Timeout kann es verändert haben. Beide als gleichartige Ausnahme zu behandeln, ist eine häufige Ursache doppelter Datensätze.

Was n8n bietet. n8n bietet „Retry On Fail“ sowie die Kombination aus Schleife und Warte-Schritt, um Aufrufe zeitlich zu steuern. Die offizielle Anleitung zu Rate Limits beschreibt diese Möglichkeiten. Prüfen Sie die Wiederholungszahl und Wartezeit im konkret verwendeten Node; eine einfache Wiederholungseinstellung ist keine vollständige geschäftliche Wiederanlauflogik.

Zeitbudget. Legen Sie für jeden wiederholbaren Aufruf ein Zeitbudget fest. Ein interner Bericht darf vielleicht nach einigen Minuten erneut angefordert werden. Eine Terminbestätigung benötigt möglicherweise eine schnellere Entscheidung oder einen manuellen Ersatzweg. Wiederholungen sollten irgendwann in einen sichtbaren offenen Fall münden, statt unbegrenzt Ressourcen zu verbrauchen.

Gemeinsame Limits. Wenn mehrere Workflows dieselbe API nutzen, betrachten Sie deren gemeinsame Last. Jeder einzeln langsame Workflow kann zusammen trotzdem ein Limit überschreiten. Die Aufrufplanung sollte deshalb die tatsächlich gemeinsame Grenze berücksichtigen, etwa ein Konto, einen Mandanten oder einen API-Schlüssel.

Wartevorgaben des Anbieters. Beachten Sie Vorgaben des Anbieters zur Wartezeit vor der nächsten Anfrage, soweit vorhanden. Kann ein Workflow die erforderliche dynamische Verzögerung nicht direkt abbilden, bauen und testen Sie einen ausdrücklich definierten Ablauf zur zeitlichen Steuerung der Anfragen, statt anzunehmen, dass eine feste Pause jede Antwort korrekt behandelt.

Beispiel. Das folgende Beispiel ist konstruiert. Ein Workflow sendet die Anlage eines Serviceauftrags mit der externen Referenz REQ-2048. Das Zielsystem legt den Auftrag an, aber die Antwort geht auf dem Rückweg verloren. n8n sieht einen Timeout. Ein vollständiger Neustart könnte nun einen zweiten Auftrag erzeugen.

Unklarer Zustand. Ein belastbarer Ablauf behandelt diesen Zustand als unklar, nicht sofort als fehlgeschlagen. Zuerst wird geprüft, ob im Zielsystem bereits ein Auftrag mit der Referenz existiert. Gibt es genau einen Treffer, wird seine Ziel-ID übernommen. Gibt es keinen, kann ein weiterer Versuch zulässig sein. Mehrere Treffer erfordern Klärung.

Idempotenz. Am besten unterstützt die Ziel-API einen ausdrücklich dokumentierten Idempotenzmechanismus. Dann wird derselbe Schlüssel für denselben fachlichen Vorgang verwendet. Ein solches Verhalten darf nicht einfach vorausgesetzt werden. Wenn die API keinen verlässlichen Schutz bietet, kann für folgenreiche Aktionen eine manuelle Entscheidung sicherer sein.

Parallelität. Auch eine Suche vor dem Schreiben allein beseitigt nicht jedes Risiko. Zwei parallel gestartete Ausführungen könnten beide „noch nicht vorhanden“ sehen und anschließend schreiben. Für solche Fälle braucht die gewählte Architektur eine wirksame Eindeutigkeitsregel oder kontrollierte Serialisierung. Die Lösung muss am konkreten Zielsystem geprüft werden.

Fehler-Workflow. Ein zentraler Fehler-Workflow kann technische Störungen melden. n8n verknüpft ihn in den Workflow-Einstellungen mit dem Hauptablauf; sein Startpunkt ist ein Error Trigger. Die Dokumentation zur Fehlerbehandlung beschreibt die Einrichtung und die Fehlerdaten.

Fachliche Ausnahmen. Nicht jede fachliche Ausnahme muss dabei als technischer Absturz modelliert werden. Ein fehlender Kundenbezug kann absichtlich in eine Klärungsliste laufen und dort als offener Fall sichtbar bleiben. Entscheidend ist, dass dieser Zustand in der Prozessüberwachung vorkommt. „Kein technischer Fehler“ darf nicht mit „geschäftlich erledigt“ verwechselt werden.

Stop and Error. Für unerwartete oder bewusst als schwerwiegend definierte Zustände kann ein Stop-and-Error-Schritt sinnvoll sein. Vergeben Sie dabei verständliche Fehlerkategorien. „Kontaktzuordnung mehrdeutig“ hilft dem Team mehr als ein beliebiger interner Variablenname.

Zuständigkeit. Regeln Sie die Zuständigkeit konkret. Die Datenklärung kann bei der Vertriebsassistenz liegen, abgelaufene Anwendungsberechtigungen dagegen bei der Identitätsadministration. Ein gemeinsames Support-Postfach kann beides empfangen, aber die Betriebsanweisung muss benennen, wer das jeweilige Problem tatsächlich lösen kann.

Automatischer Startweg. Der Error Trigger reagiert laut offizieller Node-Dokumentation auf Fehler automatisch gestarteter Workflows; ein manueller Testlauf im Editor prüft diesen Pfad nicht auf dieselbe Weise. Testen Sie den Alarm deshalb über den vorgesehenen automatischen Start in einer kontrollierten Umgebung.

Fehler im Trigger. Prüfen Sie außerdem einen Fehler im Trigger selbst. In diesem Fall können andere Informationen verfügbar sein als bei einem späteren Node-Fehler. Eine Alarmvorlage darf nicht blind voraussetzen, dass immer eine Ausführungs-ID oder ein Link zur gespeicherten Ausführung existiert.

Inhalt der Meldung. Eine gute Meldung nennt Prozess, Fehlerkategorie, Vorgangsreferenz und zuständige Person. Sensible Nutzdaten bleiben im geschützten System. Der Alarmkanal erhält nur die Informationen, die zur Einordnung notwendig sind.

Für einen mehrstufigen Vorgang eignet sich ein einfaches, ausdrücklich definiertes Zustandsmodell:

• eingegangen
• validiert
• Zielaktion bestätigt
• Nacharbeit offen
• abgeschlossen

Speichern Sie nur die Zustände, die für Nachvollziehbarkeit und sichere Fortsetzung tatsächlich benötigt werden.

Am fehlenden Schritt fortsetzen. Wenn der Auftrag bereits angelegt wurde, aber eine interne Benachrichtigung scheitert, muss nicht die Auftragsanlage wiederholt werden. Der nächste Versuch sollte bei der fehlenden Nachricht ansetzen. Prüfen Sie dabei, ob die Nachricht inzwischen auf anderem Weg versendet wurde und ob ihr Inhalt noch aktuell ist.

Nachweis. Ein Zustand muss mit der zugehörigen Zielreferenz zusammenpassen. „Geschrieben“ ohne Ziel-ID lässt sich schwer überprüfen. „Abgeschlossen“ trotz offener Pflichtprüfung ist fachlich falsch. Das Team sollte diese Regeln anhand konkreter Fälle erklären können. Ein grüner Node im Editor genügt dafür nicht.

Testen Sie für die n8n-Fehlerbehandlung mindestens diese Fälle:

• einen temporären Ausfall
• ein dauerhaft ungültiges Feld
• einen entzogenen Zugang
• eine verlorene Antwort nach erfolgreichem Schreiben
• dieselbe Eingabe zweimal

Ergänzen Sie parallele Zustellungen, wenn sie im realen Prozess auftreten können.

Erwartete Ergebnisse. Für jeden Fall legen Sie vorab fest:

• erwarteter Zustand
• erlaubte Wiederholungen
• sichtbare Meldung
• manuelle Zuständigkeit
• erwartete Zahl der Zielobjekte

Das wichtigste Ergebnis lautet häufig „genau ein fachlicher Vorgang“, nicht „irgendwann grün“. Erst wenn dieser Zusammenhang nachgewiesen ist, sind automatische Wiederholungen für den betreffenden Schritt verantwortbar.

Diese Seiten behandeln die Leistungsübersicht und die angrenzenden Entscheidungen zur n8n-Fehlerbehandlung:

• n8n-Agentur: Umsetzung und Betrieb von Unternehmensworkflows
• n8n mit APIs und Webhooks verbinden: Integrationsgrundlagen
• n8n-Wartung: Monitoring, Updates und Verantwortliche
• Doppelte Rechnungen erkennen: Regeln vor KI

Für eine konkrete Ablaufprüfung reichen zunächst eine Prozessbeschreibung, die beteiligten Systeme und typische Ausnahmen. Mit modernagents besprechen.