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. Orderport benachrichtigt Sie per E-Mail; als Administrator können Sie die Nachricht danach manuell wieder anstoßen (beides weiter unten auf dieser Seite).

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 permanently_failed, ohne Retry:

• Transformation-Fehler (Parsing, Mapping-Regel-Fehler): Wiederholen würde dasselbe Ergebnis liefern. Nach einer Korrektur der Regeln stoßen Sie die Nachricht manuell wieder an (siehe „Erneut zustellen")
• Ungültige Pipeline-Konfiguration: z. B. Shopware-Adapter ohne sales_channel_id → Pipeline muss korrigiert werden

HTTP-Fehler Ihres Zielsystems – auch dauerhaft wirkende wie 400, 404, 422 oder 501 – behandelt Orderport dagegen wie jeden anderen Fehlschlag: Sie durchlaufen die volle Retry-Kette und erreichen permanently_failed erst nach dem 5. Versuch. Wenn Sie erkennen, dass Ihr System die Daten grundsätzlich ablehnt, warten Sie die Kette nicht ab – beheben Sie die Ursache und nutzen Sie „Erneut zustellen".

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#

Beide Aktionen finden Sie auf der Detailseite einer Bestellung, sobald ihr Status failed oder permanently_failed ist. Sie sind Administratoren vorbehalten.

Erneut zustellen#

Button „Erneut zustellen". Setzt den Status auf queued und lässt die Nachricht vollständig neu laufen – Transformation und Zustellung. Genau deshalb hilft der Button nach einem Transformationsfehler: Haben Sie die Mapping-Regeln korrigiert, läuft das gespeicherte Eingangsdokument erneut durch die korrigierte Pipeline. Der Versuch zählt als eigenständig – wenn er scheitert, startet die Retry-Kette von vorn.

Voraussetzung ist, dass das Eingangsdokument noch vorliegt. Nach der 90-Tage-Aufbewahrung ist es gelöscht; der Button verschwindet dann, weil es nichts mehr zu transformieren gibt.

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.

Benachrichtigung bei endgültigem Fehlschlag#

Erreicht eine Nachricht den Status permanently_failed, schickt Orderport eine E-Mail an alle aktiven Nutzer Ihres Kontos, die Zugriff auf die betroffene Pipeline haben. Die Mail nennt Bestellnummer und Pipeline und verlinkt direkt auf die Detailseite.

Pro Pipeline geht höchstens eine Meldung je Stunde raus. Eine fehlerhafte Mapping-Regel lässt sonst jede Bestellung derselben Pipeline scheitern – Sie hätten hundert gleichlautende Mails im Postfach statt einer. Weitere Fehlschläge derselben Pipeline sehen Sie in der Bestell-Liste unter dem Status-Filter Endgültig fehlgeschlagen.

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)

1a. permanently_failed durch einen Transformationsfehler#

Ursache: Das Eingangsdokument ließ sich nicht umwandeln – etwa eine Mapping-Regel, die auf ein Feld zeigt, das im Dokument fehlt. Transformationsfehler führen sofort zu permanently_failed, ohne Retry. Die Detailseite zeigt den Versuch unter Zustellversuche als Transformationsfehler; der Grund steht unter Details.

Lösung:

1. Mapping-Regel oder Pipeline-Konfiguration korrigieren
2. Bestellung öffnen, „Erneut zustellen" klicken – die Transformation läuft mit den korrigierten Regeln neu

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
• inbound.redelivered – eine Nachricht wurde manuell erneut zugestellt
• inbound.manually_resolved – eine Nachricht wurde manuell als zugestellt markiert
• pipeline.deactivated – Pipeline wurde deaktiviert
• credential.revoked – Credential wurde widerrufen

Nächste Schritte#

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