Fehlerpfade sind nicht „Edge Cases" – sie sind Betrieb
Wenn ein Workflow produktiv läuft, passieren Fehler. Nicht vielleicht. Garantiert:
- APIs fallen aus (Wartung, Outages, Rate Limits)
- Netzwerke haben Timeouts (Latenz-Spitzen, DNS-Probleme)
- Datenvalidierung schlägt fehl (fehlende Felder, falsche Formate)
- Webhooks feuern doppelt (Retries, Netzwerk-Hickser)
Die Frage ist nicht, ob Fehler passieren – sondern was dann passiert.
Ein Workflow ohne Error-Handling ist ein Workflow, der still versagt, Daten verliert oder Duplikate erzeugt. Dieser Guide zeigt, wie ihr produktionsreife Fehlerpfade in n8n baut.
Die drei Säulen des Error-Handlings
- Retries – Automatische Wiederherstellung bei temporären Fehlern
- Dead-Letter – Erfassung von Fehlern, die nicht auto-reparierbar sind
- Idempotenz – Verhinderung doppelter Seiteneffekte
Meistert diese drei, und eure Workflows werden produktionsreif.
1) Retry-Regeln (Copy/Paste)
Nicht jeder Fehler sollte einen Retry auslösen. Einen Validierungsfehler zu wiederholen verschwendet Ressourcen und verzögert Alerts.
| Fehlerart | HTTP-Code | Retry? | Strategie |
|---|---|---|---|
| Timeout/Netzwerk | - | Ja | 3 Versuche: 1m, 5m, 30m |
| Server-Fehler | 5xx | Ja | 3 Versuche mit exponentiellem Backoff |
| Rate Limit | 429 | Ja | Retry-After Header respektieren, Jitter |
| Auth abgelaufen | 401 | Ja | Token refreshen, dann 1x retry |
| Validierung | 400/422 | Nein | Sofort in Dead-Letter |
| Not Found | 404 | Nein | Dead-Letter + untersuchen |
| Logik-Fehler | - | Nein | Workflow stoppen, Alert, Code fixen |
n8n-Implementierung:
In den Node-Settings:
- "Continue On Fail" aktivieren
- Error-Workflow Trigger hinzufügen
- IF-Node zur Fehlertyp-Prüfung
- Retry-fähige Fehler zu Wait-Node routen
- Permanente Fehler zu Dead-Letter routen
Backoff mit Jitter-Formel:
wait_time = base_delay * (2 ^ attempt) + random(0, 1000ms)
Jitter verhindert Thundering Herd, wenn mehrere Workflows gleichzeitig retrien.
2) Dead-Letter Queue (Nichts verschwindet still)
Eine Dead-Letter Queue erfasst Runs, die nicht automatisch reparierbar sind. Ohne sie verschwinden Fehler in Logs, die keiner liest.
Minimum Dead-Letter-Felder:
| Feld | Warum |
|---|---|
| timestamp | Wann es fehlschlug |
| workflow_id | Welcher Workflow |
| execution_id | Link zur n8n-Execution |
| trigger_data | Input-Snapshot (PII-minimiert) |
| error_code | HTTP-Status oder Fehlertyp |
| error_message | Was schiefging |
| correlation_id | Trace über Systeme hinweg |
| recommended_action | Was als nächstes passieren soll |
| retry_count | Wie viele Versuche gemacht |
n8n Dead-Letter Workflow:
- Trigger: Error-Workflow erhält fehlgeschlagene Execution
- Extrahieren: Fehlerdetails aus Execution-Daten holen
- Anreichern: Correlation ID, Timestamp, empfohlene Aktion hinzufügen
- Speichern: In Supabase/Airtable/Notion-Tabelle schreiben
- Alerting: Slack/Email-Notification für hochpriore Fehler
Alert-Schwellen-Logik:
- Sofort-Alert: Payment-Fehler, kundenrelevante Fehler
- Täglich gebündelt: Validierungsfehler, Datenqualitätsprobleme
- Wöchentliches Review: Niedrig-priore, erwartete Fehler
3) Idempotenz: Doppelaktionen verhindern
Der gleiche Trigger kann doppelt feuern. Netzwerk-Retries, Webhook-Replay, User-Doppelklicks. Euer Workflow muss das handlen.
Typische Duplikat-Probleme:
- 2x E-Mail an gleichen Empfänger gesendet
- 2x Ticket für gleiches Problem erstellt
- 2x CRM-Deal für gleichen Lead angelegt
- 2x Payment für gleiche Bestellung verarbeitet
Idempotency-Key-Pattern:
idempotency_key = hash(source_system + source_id + action_type)
Beispiel:
key = hash("webhook" + "order_123" + "send_confirmation_email")
n8n-Implementierung:
- Idempotency-Key aus Input-Daten generieren
- Prüfen ob Key in eurem Idempotency-Store existiert (Redis, DB-Tabelle)
- Falls existiert: Aktion skippen, als Duplikat-Prevented loggen
- Falls nicht existiert: Aktion ausführen, Key mit TTL speichern (z.B. 24h)
Idempotency-Store Schema:
CREATE TABLE idempotency_keys (
key TEXT PRIMARY KEY,
created_at TIMESTAMPTZ DEFAULT NOW(),
workflow_id TEXT,
action_type TEXT,
expires_at TIMESTAMPTZ
);
4) Security-Überlegungen
Fehlerdaten enthalten oft sensible Informationen. Sorgfältig behandeln:
- Logs: PII vor dem Loggen strippen. Keine E-Mails, keine Namen, keine IDs.
- Dead-Letter Storage: Separate Tabelle mit eingeschränktem Zugriff
- Alert-Messages: Fehlertyp inkludieren, nicht Fehlerdetails
- Retention: Dead-Letter-Einträge nach 30 Tagen auto-löschen
- Zugriff: Nur Workflow-Owner sehen vollständigen Fehler-Kontext
PII-Stripping Beispiel:
const sanitized = {
...errorData,
email: errorData.email ? "***@***.***" : null,
name: errorData.name ? "[REDACTED]" : null,
payload: "[Siehe Execution-Logs]"
};
KPIs für Error-Path-Health
Wöchentlich tracken:
| Metrik | Zielwert | Warn-Schwelle |
|---|---|---|
| Retry-Erfolgsrate | > 80% | < 60% = untersuchen |
| Dead-Letter-Volumen | Trend nach unten | Spike = neuer Bug |
| Duplikat-Prevention Hits | < 5% der Runs | > 10% = Upstream-Problem |
| Mean Time to Resolution | < 24h | > 48h = Prozess-Problem |
| Ungelöste Dead-Letters | 0 | > 10 = Backlog baut sich auf |
Quick-Start Checkliste
Bevor ein Workflow in Produktion geht:
- Error-Workflow konfiguriert
- Retry-Logik für temporäre Fehler
- Dead-Letter-Erfassung für permanente Fehler
- Idempotency-Keys für Seiteneffekte
- PII aus Logs gestripped
- Alert-Channel konfiguriert
- Dead-Letter-Review geplant (wöchentlich)
Nächster Schritt
Error-Handling ist Betriebsinfrastruktur. Einmal bauen, überall nutzen. Jeder neue Workflow erbt die gleichen Error-Patterns.