Robuste Retry-Strategien für API-Aufrufe in n8n: Exponentielles Backoff, Max-Retries und Fehler-Handling

Dieser Artikel zeigt praxisnah, wie du in n8n fehlgeschlagene API-Aufrufe zuverlässig wiederholst: mit einem einfachen, implementierbaren Aufbau für exponentielles Backoff, eine feste Anzahl von Versuchen, sinnvoller Verzögerung und einem sauberen Fehler-Handling.

Szenario und Ziel

Annahme: Ein Webhook triggert einen Workflow, der einen externen API-Aufruf macht. Netzwerkausfälle, Ratenbegrenzungen oder temporäre Serverfehler (5xx) können den Aufruf zeitweise zum Scheitern bringen. Ziel ist ein wiederholtes Versuchen mit wachsender Wartezeit (Backoff) und einer definierten Obergrenze für Versuche. Bei endgültigem Fehlschlag soll ein Error-Workflow oder ein Logging/Alert ausgelöst werden.

Architektur-Pattern (übersichtlich)

Webhook-Trigger → Initiales Set (Meta: attempt, maxAttempts, baseDelay)
HTTP Request (API-Aufruf)
IF-Node: Erfolg? → Ja: Weiterverarbeiten / Antwort; Nein: Versuchszähler prüfen
Wenn Versuche verbleiben → Delay (exponentiell berechnet) → erneut API-Aufruf
Wenn keine Versuche mehr → Error-Workflow / Alert / Persistenz

Hinweis: n8n-Workflows sind gerichtete Graphen. Für eine dynamische, beliebig lange Schleife gibt es mehrere Ansätze (siehe weiter unten). Für viele praktische Fälle ist ein kleines, festes Anzahl-von-Retries-Setup am einfachsten umzusetzen.

Konkrete Implementierung — einfache und robuste Variante (bis z.B. 3–5 festgelegte Versuche)

Diese Variante vermeidet zyklische Graphen: du erstellst mehrere, hintereinandergeschaltete Versuchs-Pfade (Attempt 1, Attempt 2, ...). Jeder Versuch besteht aus einem HTTP Request-Node und einem IF-Node. Zwischen fehlgeschlagenen Versuchen liegt ein Delay-Node mit exponentiellem Backoff.

Schritt-für-Schritt

Webhook: Eingangspayload.
Set (optional): Initialisiere Felder, z. B. attempt = 1, maxAttempts = 3, baseDelay = 5 (Sekunden).
HTTP Request (Attempt 1): Konfiguriere API-Endpunkt, Authentifizierung, Timeouts. Stelle sicher, dass der Node die Antwort inkl. statusCode ausgibt.
IF: Bedingung für Erfolg prüfen. Beispiel-Ausdruck (n8n-Expression):
```
{{ $json["statusCode"] >= 200 && $json["statusCode"] < 300 }}
```
Wenn true → Erfolgspfade (weitere Verarbeitung / Webhook-Response).
Wenn false und attempt <= maxAttempts:
- Set-Node (oder Function): erhöhe attempt (z. B. von 1 auf 2) und berechne Delay in Sekunden.
- Delay-Node: wende exponentiellen Backoff an (siehe Beispiel-Expression weiter unten).
- Verbinde zu HTTP Request (Attempt 2) → wieder IF prüfen.
Wenn nach maxAttempts noch kein Erfolg: Route in einen Error-Workflow (über Execute Workflow oder Webhook Response / Notify), schreibe Status in Log/DB oder sende Alert.

Beispiel: Function-Node zur Inkrementierung und Delay-Berechnung

Im Function-Node kannst du kleine JS-Snippets nutzen. Hier ein Beispiel, das attempt erhöht und eine Delay-Dauer (Sekunden) berechnet:

const item = items[0];
const json = item.json || {};
json.attempt = (json.attempt || 1) + 0; // falls bereits gesetzt
const attempt = (json.attempt || 1) + 1; // nächster Versuch
json.attempt = attempt;
// baseDelay in Sekunden (z.B. 5), maxDelay in Sekunden (z.B. 60)
const baseDelay = json.baseDelay || 5;
const maxDelay = json.maxDelay || 60;
const delaySeconds = Math.min(maxDelay, Math.pow(2, attempt - 1) * baseDelay);
json.delaySeconds = delaySeconds;
item.json = json;
return [item];

Erklärung: Für attempt=1 ergibt sich delay = baseDelay*2^(1-1) = baseDelay, für attempt=2 = baseDelay*2 usw. Begrenze mit maxDelay.

Delay-Node: dynamische Verzögerung

Konfiguriere den Delay-Node so, dass er die berechnete Dauer verwendet. In n8n-Ausdrücken kannst du z. B. folgendes setzen (Sekunden):

{{ $json.delaySeconds }}

Je nach n8n-Version wählst du im Delay-Node "Delay for" und als Einheit Sekunden. Alternativ kannst du eine feste Anzahl Sekunden wählen.

IF-Node-Bedingungen und Fehlerkriterien

HTTP-Statuscodes 200–299 gelten typischerweise als Erfolg: {{ $json["statusCode"] >= 200 && $json["statusCode"] < 300 }}
Client-Fehler (4xx) sollten meist nicht wiederholt werden, außer bei temporären 429 (Rate Limit) — hier lohnt ein Retry nach Wartezeit.
Server-Fehler (5xx) sind gute Kandidaten für Retries.
Bei 429: Prüfe Header wie Retry-After und verwende diese Information für den Delay.

Alternative: Dynamische Retries mit State-Persistenz (fortgeschritten)

Für flexibel viele Versuche oder verteilte Retry-Mechanismen empfiehlt sich ein externes Status-Backend (z. B. Datenbank, Redis) plus ein separater „Retry-Worker“-Workflow, der periodisch (Cron) Einträge abarbeitet. Ablauf:

Beim ersten Fehlschlag schreibe Request-Payload, ID und attempt in die DB.
Ein Scheduler-Workflow liest fällige Einträge, führt den API-Aufruf aus und aktualisiert attempt und nextAttemptAt nach exponentiellem Backoff.
Vorteil: robuste Wiederaufnahme nach n8n-Restarts, zentralisierte Kontrolle, einfache Beobachtbarkeit.

Dieses Pattern ist empfehlenswert, wenn du viele Requests koordinieren musst oder Retries über längere Zeiträume verteilen willst.

Best Practices

Idempotenz: Versende eine eindeutige Request-ID oder Idempotency-Key in Headern, damit wiederholte Anfragen beim Zielserver nicht zu Duplikaten führen.
Timeouts: Setze im HTTP Request Node sinnvolle Connect- und Read-Timeouts, damit ein einzelner Versuch nicht ewig blockiert.
Max Attempts: Lege eine Obergrenze fest (z. B. 3–10), um Endlosschleifen zu vermeiden.
Rate Limits: Berücksichtige Ratenbegrenzungen des API-Anbieters (verwende Retry-After-Header wenn vorhanden).
Observability: Logge jeden Versuch mit Attempt-Nummer und Antwortcode (z. B. in einer DB oder externem Logging-Service).
Fehler-Workflow: Nimm n8n's Error Trigger oder einen separaten Workflow, um Benachrichtigungen/Alarmierungen bei endgültigem Fehlschlag zu senden.

Fehlerbehebung und typische Fallen

Wenn Retries sofort wieder fehlschlagen: prüfe, ob das Problem serverseitig ist (z. B. falsche Auth, 4xx → keine Retries).
Delay- oder Expression-Syntax: teste Expressions im n8n-Expression-Editor, um Syntaxfehler zu vermeiden.
Bei großen Mengen an Retries: Achte auf API-Rate-Limits und erhöhe Backoff-Strategie oder nutze Queues.

Fazit

Mit einem pragmatischen Setup (einige hintereinandergeschaltete Versuche mit exponentiellem Backoff) lassen sich die meisten temporären API-Fehler in n8n zuverlässig auffangen. Für skalierbare, langlebige Retries empfiehlt sich ein externes State-Backend und ein Scheduler-Workflow. Achte in jedem Fall auf Idempotenz, sinnvolle Timeouts und observables Logging, damit Fehler reproduzierbar und handhabbar bleiben.