Fehlerbehebung#

Wenn eine Bestellung nicht durchkommt, haben Sie mehrere Werkzeuge: die automatische Retry-Logik, die Bestellungs-Detailansicht mit Transport-Logs und die manuelle Wiederholung. Diese Seite beschreibt, wie diese Werkzeuge zusammenarbeiten, welche typischen Fehlerbilder auftreten – und wie Sie sie lösen.

Automatische Wiederholung#

Schlägt ein Zustellversuch fehl (Timeout, HTTP-Fehler, Netzwerk, Auth-Problem), startet Orderport einen Retry-Job mit wachsendem Abstand:

Nach dem 5. Fehlschlag wird die Nachricht auf permanently_failed gesetzt. Sie können sie danach manuell wieder anstoßen (siehe unten).

Pro Versuch werden alle Transporte durchgespielt#

Eine Pipeline kann mehrere Transporte mit unterschiedlicher Priorität haben. Pro Versuch wird jeder aktive Transport (in Prioritäts-Reihenfolge) angesprochen, bis einer Erfolg meldet. Erst wenn alle scheitern, wird ein neuer Versuch eingereiht.

Welche Fehler werden NICHT wiederholt?#

Einige Fehler sind nicht transient und führen sofort zu failed ohne Retry:

• Transformation-Fehler (Parsing, Mapping-Regel-Fehler): Wiederholen würde dasselbe Ergebnis liefern.
• Ungültige Pipeline-Konfiguration: z. B. Shopware-Adapter ohne sales_channel_id → Pipeline muss korrigiert werden
• Permanente HTTP-Fehler (400 / 404 / 422 / 501) werden als „permanently failed" markiert, nicht retryt

Bestellungs-Detailseite#

In der Bestell-Liste (Bestellungen in der Sidebar) klicken Sie auf eine Bestellung. Die Detailseite zeigt:

• Kopf: Pipeline, Status, Empfangs-Zeitstempel, externe Bestellnummer
• Rohdaten (raw_payload): Was angekommen ist
• Transformiertes Payload (transformed_payload): Was an das Ziel geht
• Transport-Log: Pro Versuch eine Zeile mit Transport, HTTP-Status, Antwortzeit, Antwort-Body (gekürzt)

Für ältere Bestellungen (> 90 Tage) sind die Payload-Felder geleert – nur Header und Transport-Logs bleiben.

Manuelle Aktionen#

Erneut zustellen#

Auf der Detailseite: Button „Erneut zustellen". Setzt den Status auf queued und triggert einen neuen Transport-Versuch. Der Versuch zählt als eigenständig – wenn er scheitert, startet die Retry-Kette von vorn.

Manuell als zugestellt markieren#

Sonderfall: Wenn Sie wissen, dass die Bestellung außerhalb von Orderport (z. B. telefonisch oder per Copy-Paste) schon weitergeleitet wurde und Sie den Nachrichtensatz einfach abschließen möchten. Setzt Status auf delivered, löst aber keine neue Zustellung aus.

Typische Fehlerbilder#

1. permanently_failed trotz lauffähigem Zielsystem#

Ursache: Zielsystem war zum Zeitpunkt aller 5 Versuche down (Wartungsfenster, Migration).

Lösung:

1. Ziel-System wieder verfügbar machen
2. Bestellung öffnen, „Erneut zustellen" klicken
3. Falls mehrere Nachrichten betroffen: nacheinander erneut zustellen (Bulk-Aktion ist in Planung)

2. Bestellung eingelaufen, aber nicht zugestellt – Status bleibt queued#

Ursache: Queue-Worker hängt oder wurde neu gestartet. Sehr selten – auf Orderports Infrastruktur überwacht.

Lösung: Meldung an Support. Nach Worker-Recovery greift die Nachricht wieder zur Verarbeitung.

3. Mehrfache Zustellung beim Ziel#

Ursache: Ziel-System antwortet langsamer als 30 Sekunden oder gibt keinen HTTP-Status zurück. Orderport wertet das als Fehler, Retry liefert dieselbe Nachricht ein zweites Mal.

Lösung:

• Ziel-System so bauen, dass es schnell Annehme-Bestätigung liefert und asynchron verarbeitet
• Alternativ: REST-API-Transport mit erhöhtem Timeout verwenden (timeout-Parameter in Transport-Config)

4. Duplicate-Meldung bei Shopify-Retry#

Ursache: Shopify wiederholt fehlgeschlagene Webhooks bis zu 19 Mal. Orderports Duplikatserkennung antwortet auf den zweiten Versuch mit HTTP 409.

Lösung: Kein Handlungsbedarf. Shopify wertet 409 als „erledigt" und stellt die Wiederholungen ein. Die erste erfolgreiche Einlieferung wird normal verarbeitet.

5. HTTP 401 bei einem Shopware-6-Adapter#

Ursache: OAuth-Token abgelaufen oder Client-Secret rotiert.

Lösung:

1. In Shopware 6 → Integrationen → Access Key / Secret erneuern
2. In Orderport → Transport editieren → Client-Secret neu eintragen
3. Verbindung testen

6. FTP-Upload landet nicht im Zielverzeichnis#

Ursache: Benutzer hat Schreibrechte, aber nicht das Rename-Recht (Orderport schreibt erst .tmp und benennt nach Erfolg um).

Lösung: Mit dem Partner klären; Benutzer muss CWD + Upload + Rename dürfen.

7. Credential funktioniert plötzlich nicht mehr#

Ursache: Secret wurde rotiert, Partner noch nicht umgestellt – oder umgekehrt.

Lösung:

• Parallele Credentials: alte aktiv lassen, neue anlegen, Partner umschwenken, alte deaktivieren
• Im Audit-Log nach credential.deleted / credential.revoked suchen

8. Pipeline inaktiv, aber Bestellung wurde erwartet#

Ursache: Aktivieren wurde vergessen, oder jemand hat sie deaktiviert.

Lösung: Pipeline-Detailseite → Aktivieren. Im Audit-Log finden Sie den Eintrag pipeline.deactivated mit Benutzer und Zeitstempel.

Wann Sie Support kontaktieren sollten#

• Queue-Worker scheinen zu hängen (mehrere Nachrichten bleiben > 15 Min. in queued)
• Unerwartete HTTP 5xx aus Orderport selbst (nicht aus dem Ziel)
• Ungewöhnliche Meldungen im Audit-Log, die Sie nicht selbst ausgelöst haben

Am schnellsten sind Support-Anfragen mit: Message-ID oder Pipeline-ID + Zeitpunkt + beobachtetes Verhalten.

Technische Details#

Retry-Parameter#

• Maximale Versuche: 5
• Backoff in Sekunden: 60, 300, 1 800, 7 200, 86 400 (entspricht 1 min, 5 min, 30 min, 2 h, 24 h)
• Pro Nachricht läuft stets nur ein Versuch gleichzeitig; parallele Zustellungen derselben Nachricht sind ausgeschlossen.

Audit-Log-Einträge#

Die wichtigsten Ereignisse, die im Fehlerkontext auftauchen:

• inbound.cxml_auth_failed – eingehende Authentifizierung fehlgeschlagen
• inbound.duplicate_rejected – eine bereits bekannte Bestellung wurde erneut eingeliefert
• pipeline.deactivated – Pipeline wurde deaktiviert
• credential.revoked – Credential wurde widerrufen

Nächste Schritte#

• Eingangsnachrichten – Status-Lebenszyklus
• Limits & Kontingente
• Audit-Log