Zusammenfassung

  • Für POST in API v1 speichert Stripe Status und Inhalt der ersten Antwort, sobald die Ausführung begonnen hat, auch bei 500. Derselbe Schlüssel liefert während seiner Aufbewahrung das gespeicherte Ergebnis.
  • Hinter einer 500 können bereits Nebenwirkungen stehen. Stripe kann später abgleichen und einen Webhook für ein erzeugtes Objekt senden; die gespeicherte Antwort ändert sich dabei nicht. API v2 behandelt Wiederholungen anders.

Der rote Beleg bleibt stehen

Ein Dienst schickt eine Anweisung an Stripe, erhält 500 und versucht es mit demselben Schlüssel erneut. Wieder 500. Die zweite Antwort sieht nach einem zweiten Fehlschlag aus, kann bei API v1 aber nur eine Kopie sein. Stripe hält die erste Antwort fest, nachdem der Endpunkt mit der Ausführung begonnen hat. Idempotent-Replayed: true kennzeichnet die Wiedergabe. Ein Alarmzähler, der beide Antworten als neue Fehlschläge bewertet, misst Belege statt Geschäftsergebnisse.

Stripe bezeichnet die Wirkung einer 500 als unbestimmt: Die ursprüngliche Operation kann Nebenwirkungen ausgelöst haben. Bei der Wiederherstellung versucht Stripe fehlgeschlagene Vorgänge abzugleichen und kann für erzeugte Objekte Webhooks verschicken. Die gecachte 500 wird dadurch nicht überschrieben. Umgekehrt garantiert Stripe nicht, dass jeder Abgleich gelingt. Genau deshalb braucht die Organisation einen zweiten Blick auf das Objekt und ihre eigene Auftragsidentität.

Eine lokale Vorgangs-ID gehört vor dem ersten API-Aufruf in die eigenen Unterlagen und in die Metadaten der angelegten Ressource. Bei einer 500 sucht das Team das relevante Objekt, prüft die Anforderung im Dashboard und ordnet signaturgeprüfte Webhooks zu. Solange die erste Wirkung ungeklärt ist, kann ein neuer Idempotenzschlüssel einen weiteren Vorgang eröffnen. Das wäre eine Entscheidung über Geld oder Zugang, nicht bloß eine technische Wiederholung.

Bei API v2 beschreibt Stripe eine andere Semantik: erfolgreiche Arbeit wird nicht erneut ausgeführt; fehlgeschlagene oder teilweise fehlgeschlagene Arbeit soll nach Möglichkeit abgeschlossen und mit einer aktualisierten Antwort versehen werden. Ein Migrationsplan muss deshalb die API-Version jeder Operationsklasse und ihren Wiederholungsweg nennen. „Noch einmal senden“ ist ohne diese Angabe keine Betriebsanweisung.

Quellen