Taxonomie der Zahlungsfehler (Taxonomie Der Zahlungsfehler)

Im vorherigen Teil haben wir gesehen, wie semantische Events wie PaymentFailed die Statuscodes des Providers verbergen. Doch ein einzelnes PaymentFailed-Event reicht nicht aus, denn das Wort 'fehlgeschlagen' umfasst sehr unterschiedliche Realitäten.

Eine abgelehnte Karte, ein Netzwerk-Timeout, ein PSP, der 429 zurückgibt, und ein PSP, der 500 zurückgibt, sehen alle wie 'Fehler' aus — doch jeder verlangt eine völlig andere Reaktion. Dieser Teil baut eine Taxonomie, die diese Unterschiede sichtbar macht.

PaymentFailed
  ├─ Business Decline    (Karte abgelehnt — nicht wiederholen)
  ├─ Timeout             (unklares Ergebnis — vorsichtig wiederholen)
  ├─ Rate Limited (429)  (zu viele Anfragen — mit Backoff wiederholen)
  └─ Infrastructure (5xx) (Fehler beim Provider — wiederholen)

Wo die Begriffe zuerst auftauchen

📦 Business Decline
Der PSP lehnt die Anfrage aus einem Grund ab, der mit der Karte selbst zusammenhängt: Guthaben, Betrugsverdacht.

📦 Transienter Fehler
Ein vorübergehender Fehler, bei dem ein erneuter Versuch sinnvoll ist: Timeout, 5xx, 429.

📦 Permanenter Fehler
Ein Fehler, bei dem ein erneuter Versuch nichts ändert: eine ungültige Kartennummer, eine nicht unterstützte Währung.

📦 Unklares Ergebnis
Ein Zustand, in dem unbekannt ist, ob die Anfrage den PSP überhaupt erreicht hat: ein Verbindungs-Timeout.

Einen Business Decline zu wiederholen verschwendet Zeit; ein unklares Ergebnis nicht zu wiederholen riskiert eine tatsächlich verpasste Zahlung. Die Taxonomie trennt genau diese beiden Risiken.

Die vier Grundkategorien

Business Decline: Der PSP hat die Anfrage empfangen, verarbeitet und eine Entscheidung getroffen — die Karte wurde abgelehnt. Das ist kein Systemfehler, sondern eine Geschäftsentscheidung. Ein erneuter Versuch ändert nichts; der Kunde sollte eine andere Zahlungsmethode angeboten bekommen.

Timeout / unklares Ergebnis: Die Anfrage wurde gesendet, aber keine Antwort kam an. Die Gefahr hier: Die Zahlung könnte beim PSP bereits erfolgt sein — nur die Antwort ist bei Ihnen verloren gegangen. Diese Kategorie darf nicht blind wiederholt werden; zuerst muss der tatsächliche Status abgefragt werden (mit dem Idempotency Key), erst dann entschieden werden.

Rate Limited (429): Der PSP lehnt Sie vorübergehend ab, um das Anfragevolumen zu steuern. Das ist kein Fehler, sondern ein Signal. Ein sofortiger erneuter Versuch verschlimmert die Lage; es muss mit Backoff gewartet werden.

Infrastructure (5xx): Auf der Seite des PSP ist etwas fehlgeschlagen. Die Anfrage wurde nicht verarbeitet, ein erneuter Versuch ist meist sicher — aber anhaltende 5xx-Antworten sind ein Signal für einen Circuit Breaker.

Fehler empfangen
  │
  ├─ Hat der PSP die Anfrage klar abgelehnt? → Business Decline → nicht wiederholen
  │
  ├─ Kam gar keine Antwort? → Unklares Ergebnis → zuerst Status abfragen
  │
  ├─ Ist es ein 429? → Rate Limited → mit Backoff wiederholen
  │
  └─ Ist es ein 5xx? → Infrastructure → wiederholen, aber Circuit Breaker beobachten

Warum eine einzige 'einfach wiederholen'-Regel scheitert

Ein Worker, der jeden Fehler gleich behandelt, scheitert auf zwei Arten: Er wiederholt Business Declines sinnlos (verzögert die Nutzererfahrung, belastet manchmal Kartennetzwerklimits) — oder er lässt unklare Ergebnisse gänzlich unwiederholt (das System vergisst eine tatsächlich erfolgreiche Zahlung). Die Taxonomie verringert beide Risiken, indem sie jeden Fehler in die richtige Kategorie einordnet.

Die Taxonomie im Code abbilden

Das Feld failureReason des semantischen Events sollte eine dieser vier Kategorien tragen, niemals den rohen Fehlertext des Providers. Das Provider-Gateway ist für dieses Mapping verantwortlich — eine Erweiterung des Translators aus dem vorherigen Teil.

failureReason	Wiederholung sinnvoll	Aktion
BusinessDecline	Nein	Andere Zahlungsmethode anbieten
AmbiguousTimeout	Erst abfragen	Status prüfen, dann entscheiden
RateLimited	Ja	Mit Backoff wiederholen
InfrastructureError	Ja	Wiederholen + Circuit Breaker beobachten

Häufig verwechselte Unterschiede

❌ Jeder Fehler sollte wiederholt werden
✓ Ein Business Decline sollte niemals wiederholt werden; das Ergebnis ändert sich nicht

❌ Timeout = kein Fehler, einfach wiederholen
✓ Timeout = Unklarheit; der echte Status muss zuerst abgefragt werden

❌ Ein 429 ist ein Fehler
✓ Ein 429 ist ein Signal — das System verlangsamt Sie absichtlich

Schneller Vergleich der Kategorien

Kategorie	Ergebnis bekannt	Wiederholung sinnvoll	Typische Ursache
Business Decline	ja	nein	Karte, Guthaben, Betrug
Timeout	nein	erst abfragen	Netzwerk, PSP-Langsamkeit
Rate Limited	ja	ja (mit Wartezeit)	Volumensteuerung
Infrastructure	ja	ja	Fehler beim Provider

Checkliste beim Aufbau der Taxonomie

1. Ist jeder vom Provider zurückgegebene Fehlercode explizit einer der vier Kategorien zugeordnet?
2. Was passiert bei einem noch nicht zugeordneten Fehlercode — wird standardmäßig zuerst abgefragt oder blind wiederholt? (Der richtige Standard: erst abfragen.)
3. Wird bei Timeouts vor jedem erneuten Versuch tatsächlich eine Statusabfrage durchgeführt?
4. Berücksichtigt die 429-Backoff-Dauer den Retry-After-Header des PSP, falls vorhanden?
5. Wird die 5xx-Häufigkeit als Metrik überwacht, die einen Circuit Breaker auslösen kann?
6. Gerät der Nutzerfluss nach einem Business Decline jemals versehentlich in die Retry-Schleife?

Was bleiben soll

1. 'Fehlgeschlagen' ist kein einziger Zustand, sondern mindestens vier unterschiedliche Realitäten mit vier unterschiedlichen Aktionen.
2. Business Declines werden niemals wiederholt; Timeouts werden niemals blind wiederholt, sondern zuerst abgefragt.
3. Ein 429 ist ein Signal, ein 5xx ist ein Fehler; beide werden wiederholt, aber mit unterschiedlicher Disziplin.
4. Die Taxonomie macht einen Fehler aus Ihrem eigenen failureReason-Enum lesbar, nicht aus dem rohen Providertext.

Eine Retry-Strategie, die ohne Verständnis des Fehlers geschrieben wurde, ist nicht nur nutzlos — sie schadet still.

Der nächste Teil baut für jede dieser vier Kategorien den eigentlichen Retry-Algorithmus: Backoff, Jitter, Caps und Circuit Breaker.