Zum Inhalt

ADR — 02 Retouren-Check v2: SplitInBatches+Wait statt Mega-Code-Node

Datum: 2026-05-14 Status: Akzeptiert (live) Deciders: Susi, Claude

Kontext

02 Retouren-Check v1 trackt täglich GLS+DHL-Sendungen aus dem Tracking-Sheet. Die komplette Tracking-Logik (60 fällige Items × DHL-Sleep × Retry-Backoffs) lag in einem Mega-Code-Node Tracking prüfen + Status bestimmen.

Problem: n8n Cloud Starter hat ein hartcodiertes 60s Task-Runner-Timeout für Code-Nodes (nicht erhöhbar im Starter-Plan). Symptom in Execution #1152 am 14.05.2026: 63 fällige Items, 0 prozessiert, kein Sheet-Update, 3 Min Wall-Clock-Zeit, Workflow-Status irreführend „success" weil n8n den Error-Pfad routet.

Belegt in n8n Issue #23553, #24416. Wachsende DHL-Sendungsmengen (besonders nach SUB Retoure Amazon-RSA-Auto-Anlage) machten das v1-Pattern endgültig untragbar.

Entscheidung

Architektur-Refactor in v2: Statt einer JS-Schleife im Code-Node nutzen wir SplitInBatches(1) + HTTP Request + Code + Sheet-Update + Wait(5.5s) → Loop-Pattern für DHL. Wait-Nodes pausieren den Workflow, nicht den Code-Runner — kein 60s-Limit. GLS bleibt parallel im Code-Node (schnell, kein vergleichbares Rate-Limit-Problem).

Workflow-ID v2: OZV6aC8jzVAQMAES, liegt im Folder 02 Retourencheck in Susi Projects.

Zusätzliche Features in v2:

  1. Sheet-Update pro DHL-Item (statt batch am Ende) — committet Progress sofort, auch wenn Workflow das 5-Min-Limit reißt.
  2. Prime-Branch für GLS-Prime + DHL-Prime → neuer Status amazon_extern, kein weiteres Tracking. Verhindert ewige Filter-Schleifen für Amazon-RSA-Items.
  3. Ticket-Erstellung leert naechster_check für alle Pakete einer Gruppe (vorher blieb Datum stehen → Inkonsistenz im Sheet).
  4. Status-Entscheidungslogik aus altem Mega-Code-Node 1:1 gespiegelt in zwei kleinere Code-Nodes (GLS Tracking parallel + DHL Status entscheiden).

Alternativen geprüft

Option Warum nicht
n8n Self-Hosted upgraden Würde N8N_RUNNERS_TASK_REQUEST_TIMEOUT erlauben — aber Migration aus Cloud Starter raus ist großes Projekt, andere Workflows betroffen, eigene Wartung.
n8n Cloud-Plan upgraden Keine Garantie dass das 60s-Limit im teureren Plan erhöht ist (laut n8n-Issues weiterhin nicht).
DHL-Batch-Endpoint nutzen Existiert nicht im DHL Track-API Free Tier (Single-Tracking-Number-Calls only).
DHL-Calls auf separaten Cron auslagern Würde Komplexität verschieben, nicht lösen (Worker-Workflow hätte gleiche Limits).
Async-Queue via Sheet Workflow schreibt Items in Queue-Sheet, separater Cron arbeitet ab — Overkill, mehr State-Management, schwerer zu debuggen.

SplitInBatches+Wait ist das idiomatische n8n-Cloud-Starter-Pattern für „lange Loops mit Rate-Limits".

Konsequenzen

Positiv:

  • Workflow läuft jetzt zuverlässig durch beliebig viele Items (limitiert nur durch Workflow-Timeout von 300s und DHL-Rate-Limit).
  • Sheet zeigt Progress pro Item — bei Crash mid-run gehen nur die noch nicht verarbeiteten Items verloren, der Rest ist commited.
  • Amazon-RSA-Items werden nicht mehr ewig in der Filter-Schleife rumgereicht (amazon_extern-Branch).
  • Workflow-Crash trigger jetzt 00 Error-Notifier → Slack-Post in #03_customer-support.

Negativ / Trade-offs:

  • DHL-Tracking dauert deutlich länger: ~5.5s pro Item (Wait), bei 80 Items = ~7 Min. Mit DHL-Upgrade auf höheres Rate-Limit reduzierbar auf ~0.25s/Item.
  • Workflow ist visuell komplexer (mehr Nodes statt einem Mega-Code-Node). Debugging via UI dauert länger, aber jeder Node ist kleiner und leichter zu lesen.
  • Mapping-Resolver-Issue beim Bau: n8n's AI-Builder hatte 10 von 16 Sheet-Update-Mappings auf $('Fällige Checks holen').item.json.foo umgemodelt → „Paired item data unavailable". Fix: GLS-Token-Holen an Workflow-Start verschoben + Sample-Outputs aller Code-Nodes auf 16 Felder erweitert + pairedItem-Tracking. Wenn jemand v2 forkt oder per update_workflow patcht, muss er auf dieses Pattern achten.

Migration v1 → v2

  • v1 (9qzWLsxK4GhEgrTN) ist deaktiviert, bleibt im Workspace zur Referenz.
  • Zwischenversion (sPGNJxFM8TUgkNiP) war erste v2-Iteration mit Mapping-Resolver-Issue, wurde archiviert.
  • v2 (OZV6aC8jzVAQMAES) ist live ab 14.05.2026 Cron 9:00.

Verwandt

  • 02 Retouren-Check v2 Workflow-Karte
  • SUB Retoure — produziert die DHL-Prime / GLS-Prime Items, die im neuen Prime-Branch landen.
  • ~/Desktop/CLAUDE/n8n-workflows/retouren check/retouren-workflows-empfehlungen.md — 14 Empfehlungen, von denen 7 als „noch offen" in der Workflow-Karte gelistet sind (DHL-Key in Credential, 5xx-Retry, Error-Workflow, Multi-Paket-Aggregator, error-Cutoff, Hermes-Carrier, Stufe-2-Eskalation).