# 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:

| Versuch | Wartezeit danach |
|---|---|
| 1. | 1 Minute |
| 2. | 5 Minuten |
| 3. | 30 Minuten |
| 4. | 2 Stunden |
| 5. | 24 Stunden |

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](/docs/inbound-messages) – Status-Lebenszyklus
- [Limits & Kontingente](/docs/limits-und-kontingente)
- [Audit-Log](/docs/audit-log)