Stripe-API: Paginierung und Idempotency-Keys (starting_after, has_more und das 24-Stunden-Fenster)

Worum es geht

Laut der Pagination-Referenz von Stripe "teilen" List-Methoden "eine gemeinsame Struktur und akzeptieren mindestens ... limit, starting_after und ending_before". Verwendet wird "Cursor-basierte Paginierung ... Beide Parameter akzeptieren eine bestehende Objekt-ID ... und liefern Objekte in umgekehrt chronologischer Reihenfolge"; zudem heisst es, die beiden Cursor-Parameter "schliessen sich gegenseitig aus". Jede List-Antwort verpackt die Ergebnisse als {"object": "list", "data": [...], "has_more": bool, "url": "..."}. Dabei gilt für limit der Standardwert 10 und eine Obergrenze von 100. Zusätzlich bieten die Client-Bibliotheken von Stripe "Auto-Pagination-Helfer, um alle Seiten einer Liste zu durchlaufen", sodass starting_after nur selten von Hand durchlaufen werden muss. Für schreibende Zugriffe erklärt die Idempotency-Referenz von Stripe, dass ein Client mit einem Idempotency-Key-Header "den Request sicher wiederholen kann, ohne Gefahr, ein zweites Objekt zu erzeugen oder das Update zweimal auszuführen". Der Grund: Stripe speichert "den resultierenden Statuscode und Body des ersten Requests ... unabhängig davon, ob er erfolgreich ist oder fehlschlägt". Gespeicherte Keys können gelöscht werden, sobald sie mindestens 24 Stunden alt sind (ein erneut verwendeter Key gilt dann als neuer Request). Eine erneut ausgelieferte Antwort trägt den Header Idempotent-Replayed: true. Die Wiederverwendung eines Keys mit anderen Parametern wird abgelehnt: "Die Idempotenzschicht vergleicht eingehende Parameter mit denen des ursprünglichen Requests und gibt einen Fehler zurück, wenn sie nicht übereinstimmen." Ergebnisse werden erst gespeichert, wenn die Ausführung eines Endpunkts beginnt. Ein Request, der an der Validierung scheiterte oder mit einem gleichzeitigen Request kollidierte, kann daher mit demselben Key wiederholt werden. Die Seite zu den Rate Limits von Stripe nennt ein globales Limit von 100 Requests pro Sekunde im Live-Modus und 25 in einer Sandbox, 25 pro Sekunde je Endpunkt (sofern nicht anders angegeben) sowie 20 Lese-Requests pro Sekunde für die Search API. Requests, die das Limit überschreiten, erhalten 429 plus den Header Stripe-Rate-Limited-Reason (global-rate, endpoint-rate, global-concurrency, endpoint-concurrency oder resource-specific). Ein 429 ohne diesen Header ist kein Rate Limit, sondern kann ein lock_timeout auf einem Objekt sein, das ein anderer Request gerade sperrt.

Warum es wichtig ist

Offset-basiertes Paging wird auf den v1-List-Endpunkten von Stripe gar nicht angeboten, daher funktioniert jeder clientseitige Versuch, eine Seitennummer zu berechnen, nicht. Idempotency-Keys sind der dokumentierte Weg, einen wiederholten POST (nach einem Timeout oder einer abgebrochenen Verbindung) davor zu schützen, eine doppelte Zahlung oder einen doppelten Kunden zu erzeugen.

So wird es angewendet

• Für die Entscheidung, ob eine weitere Seite abzurufen ist, has_more auswerten, nicht die Anzahl der zurückgegebenen Elemente; die id des letzten Elements als starting_after übergeben.
• Den eingebauten Auto-Pagination-Iterator der Client-Bibliothek selbst geschriebenen Schleifen vorziehen.
• Pro logischem Schreibversuch einen neuen Idempotency-Key erzeugen (Stripe empfiehlt eine v4-UUID) und denselben Key nur dann wiederverwenden, wenn exakt derselbe Request nach einem Netzwerkfehler wiederholt wird.
• Idempotency-Keys frei von sensiblen Daten halten und auf höchstens 255 Zeichen beschränken, gemäss den Vorgaben von Stripe.
• Bei 429 exponentielles Backoff mit Jitter anwenden und Stripe-Rate-Limited-Reason auswerten; die Parallelität nie erhöhen, um das auszugleichen. Keine Lasttests gegen eine Sandbox durchführen, da deren Limits niedriger sind als im Live-Modus.

Stolpersteine

Einen Idempotency-Key "sicherheitshalber" für tatsächlich verschiedene Requests wiederverwenden: Stripe behandelt eine Abweichung der Parameter als Fehler und reicht den Request nicht stillschweigend durch. Idempotency-Keys bei GET/DELETE mitsenden: Laut der Stripe-Dokumentation bleibt das wirkungslos, da diese Methoden per Definition idempotent sind.