Ratenbegrenzungen
Die Stripe-API setzt eine Reihe von Schutzmaßnahmen gegen riesige Mengen von eingehendem Datenverkehr ein, um ihre Stabilität zu maximieren. Nutzer/innen, die viele Anfragen in schneller Folge senden, sehen möglicherweise Fehlerantworten, die als Statuscode 429
gekennzeichnet sind. In der API gibt es mehrere Begrenzungen, u. a.:
Eine Ratenbegrenzung, die die Anzahl der von der API empfangenen Anfragen innerhalb einer bestimmten Sekunde begrenzt.
Für die meisten APIs erlaubt Stripe bis zu 100 Lesevorgänge pro Sekunde und 100 Schreibvorgänge pro Sekunde im Live-Modus und jeweils 10 Vorgänge pro Sekunde im Test-Modus.
Für die Dateien-API erlaubt Stripe bis zu 20 Lesevorgänge pro Sekunde und 20 Schreibvorgänge pro Sekunde, sowohl im Live- als auch im Test-Modus. Die Grenzwerte für den Live-Modus und den Test-Modus werden getrennt erfasst und sind gleich.
Für die Search API erlaubt Stripe bis zu 20 Lesevorgänge pro Sekunde. Dies gilt für alle Test-Endpoints, sowohl im Live-Modus als auch im Test-Modus. Die Grenzwerte für den Live- und den Test-Modus werden getrennt erfasst.
Eine Gleichzeitigkeitsbegrenzung, die die Anzahl der Anfragen einschränkt, die zu einem bestimmten Zeitpunkt aktiv sind. Probleme mit dieser Begrenzung treten im Vergleich zur Anfrageratenbegrenzung seltener auf. Es ist aber wahrscheinlicher, dass es zu ressourcenintensiven, langlebigen Anfragen kommt.
Behandeln Sie diese Grenzwerte als Maximalwerte und generieren Sie keine unnötige Last. Hinweise zum Umgang mit 429-Fehlern finden Sie unter Sinnvoller Umgang mit Begrenzungen. Wenn Sie plötzlich eine wachsende Anzahl von Anfragen mit Ratenbegrenzung feststellen, kontaktieren Sie bitte den Support.
Wir können Grenzwerte reduzieren, um Missbrauch zu verhindern. Außerdem können wir Grenzwerte erhöhen, um Anwendungen mit hohem Datenverkehr zuzulassen. Um eine erhöhte Ratenbegrenzung anzufordern, kontaktieren Sie den Support. Wenn Sie eine umfangreiche Erhöhung beantragen, kontaktieren Sie uns 6 Wochen bevor Sie die erhöhte Ratenbegrenzung benötigen.
Häufige Ursachen und Gegenmaßnahmen
Eine Ratenbegrenzung kann unter einer Vielzahl von Bedingungen stattfinden, kommt aber am häufigsten in den folgenden Szenarien vor:
- Die Ausführung einer großen Anzahl eng beieinander liegender Anfragen kann dazu führen, dass die Anzahl der Anfragen begrenzt wird. Dies ist häufig Teil eines Analyse- oder Migrationsvorgangs. Wenn Sie diese Aktivitäten durchführen, sollten Sie versuchen, die Anfragerate auf der Client-Seite zu steuern (siehe Sinnvoller Umgang mit Begrenzungen).
- Das Ausstellen von vielen langlebigen Anfragen kann die Begrenzung auslösen. Anfragen variieren hinsichtlich der Menge der genutzten Stripe-Serverressourcen, und ressourcenintensivere Anfragen dauern tendenziell länger und bringen die Gefahr mit sich, dass neue Anfragen durch die Gleichzeitigkeitsbegrenzung abgelehnt werden. Die Ressourcenanforderungen sind sehr unterschiedlich. Listenanfragen und Anfragen, die Erweiterungen enthalten, verbrauchen im Allgemeinen mehr Ressourcen und benötigen mehr Zeit. Wir empfehlen, die Dauer von Stripe-API-Anfragen zu profilieren und auf Zeitüberschreitungen zu achten, um zu versuchen, diejenigen Anfragen zu erkennen, die unerwartet langsam sind.
- Ein plötzlicher Anstieg des Zahlungsvolumens, z. B. bei einem Flash Sale kann zu einer Ratenbegrenzung führen. Wir versuchen, unsere Raten so hoch anzusetzen, dass bei einem Großteil unserer Nutzer/innen nie eine Ratenbegrenzung für rechtmäßigen Zahlungsverkehr stattfindet. Wenn Sie jedoch vermuten, dass ein bevorstehendes Ereignis dazu führen könnte, dass die obigen Grenzwerte überschritten werden, kontaktieren Sie bitte den Support.
Sinnvoller Umgang mit Begrenzungen
Eine grundlegende Technik zum sinnvollen Umgang mit Begrenzungen bei Integrationen besteht darin, auf 429
-Statuscodes zu achten und einen Wiederholungsmechanismus zu implementieren. Der Wiederholungsmechanismus sollte einem exponentiellen Backoff-Zeitplan folgen, um das Anfragevolumen bei Bedarf zu reduzieren. Wir empfehlen außerdem, eine gewisse Zufälligkeit in den Backoff-Plan aufzunehmen, um einen Thundering-Herd-Effekt zu vermeiden.
Einzelne Anfragen können Sie nur in begrenztem Maße optimieren. Bei einem komplexeren Verfahren steuern Sie den Datenverkehr zu Stripe auf globaler Ebene und drosseln ihn, wenn Sie eine erhebliche Ratenbegrenzung feststellen. Ein gängiges Verfahren zur Steuerung der Rate ist die Implementierung einer Art Token-Bucket-Algorithmus zur Ratenbegrenzung auf der Client-Seite. Vorgefertigte und ausgereifte Implementierungen für Token-Buckets sind in beinaher jeder Programmiersprache verfügbar.
Zeitüberschreitungen der Objektsperre
Bei Integrationen können Fehler mit dem HTTP-Status 429
, Code lock_timeout
und der folgenden Meldung auftreten:
Der Zugriff auf dieses Objekt ist zurzeit nicht möglich, da eine andere API-Anfrage oder ein anderer Stripe-Prozess darauf zugreift. Wenn dieser Fehler gelegentlich angezeigt wird, wiederholen Sie die Anfrage. Wenn Sie den Fehler häufig sehen und mehrere gleichzeitige Anfragen an ein einzelnes Objekt stellen, führen Sie Ihre Anfragen fortlaufend oder mit einer niedrigeren Rate durch.
Die Stripe-API sperrt Objekte für einige Vorgänge, damit sich gleichzeitige Arbeitslasten nicht gegenseitig beeinträchtigen und ein inkonsistentes Ergebnis erzeugen. Der obige Fehler wird durch eine Anfrage verursacht, mit der versucht wird, eine Sperre zu erzielen, die bereits an anderer Stelle gehalten wird, und die Zeitüberschreitung, nachdem sie nicht rechtzeitig erzielt werden konnte.
Zeitüberschreitungen bei Sperren haben eine andere Ursache als Ratenbegrenzungen, die Abhilfemaßnahmen sind aber ähnlich. Ebenso wie bei Ratenbegrenzungsfehlern empfehlen wir, den Versuch nach einem exponentiellen Backoff-Zeitplan zu wiederholen (siehe Sinnvoller Umgang mit Begrenzungen). Anders als bei Ratenbegrenzungsfehlern wiederholen die in die Client-Bibliotheken von Stripe integrierten Wiederholungsmechanismen Versuche mit 429
-Statuscodes, die durch Zeitüberschreitungen bei Sperren verursacht werden:
Sperrkonflikte werden durch gleichzeitige Zugriffe auf verwandte Objekte verursacht. Für Integrationen kann dies erheblich reduziert werden, indem sichergestellt wird, dass Mutationen für das gleiche Objekt in eine Warteschlange gestellt und stattdessen sequentiell ausgeführt werden. Gleichzeitige Vorgänge für die API können weiterhin durchgeführt werden. Versuchen Sie jedoch dafür zu sorgen, dass parallele Vorgänge nur für einheitliche Objekte ausgeführt werden. Es ist auch möglich, dass ein Sperrkonflikt angezeigt wird, dessen Ursache ein Konflikt mit einem internen Stripe-Hintergrundprozess ist. Dies sollte nur selten vorkommen, da es aber außerhalb der Kontrolle der Nutzer/innen liegt, wird empfohlen, dass alle Integrationen in der Lage sein sollten, Anfragen zu wiederholen.
Belastungstest
Es ist üblich, dass sich Nutzer/innen auf ein großes Verkaufsereignis vorbereiten, indem sie ihre Systeme einem Belastungstest unterziehen, wobei die Stripe-API im Test-Modus ausgeführt wird. Wir raten generell von dieser Vorgehensweise ab, da die API-Grenzwerte im Test-Modus niedriger sind, sodass beim Belastungstest möglicherweise Grenzwerte erreicht werden, die in einer Produktionsumgebung nicht erreicht werden. Außerdem ist der Test-Modus kein perfekter Ersatz für Live-API-Aufrufe, was etwas irreführend sein kann. Wird beispielsweise eine Zahlung im Live-Modus erstellt, wird eine Anfrage an ein Zahlungs-Gateway gesendet, die im Test-Modus simuliert wird, was stark unterschiedliche Latenzprofile zur Folge hat.
Als Alternative empfehlen wir, Integrationen so zu erstellen, dass sie über ein konfigurierbares System für die Simulation von Anfragen an die Stripe-API verfügen, das Sie für Belastungstests aktivieren können. Um realistische Ergebnisse zu liefern, sollten sie Latenz simulieren, indem sie sich für eine Zeit im Ruhezustand befinden, den Sie durch Messen der Dauer von Aufrufen der Stripe-API im echten Live-Modus aus der Perspektive der Integration bestimmen.
Zuordnung von API-Leseanfragen
Stripe bietet Zugriff auf seine API-Leseanfragen (GET), um angemessene Suchaktivitäten im Zusammenhang mit Zahlungsintegrationen zu erleichtern. Um die Servicequalität für alle Nutzer/innen zu maximieren, bietet Stripe die folgenden Zuordnungen für Leseanfragen basierend auf der Anzahl der Transaktionen:
- Die Anzahl der API-Leseanfragen sollte ein durchschnittliches Verhältnis von 500 Anfragen pro Transaktion für ein Konto nicht überschreiten. Wenn ein Konto beispielsweise 100 Transaktionen in einem Zeitraum von 30 Tagen verarbeitet, sollten 50.000 API-Leseanfragen in diesem Zeitraum nicht überschritten werden.
- Bei Verwendung von Connect haben eine Plattform und ihre verbundenen Konten unterschiedliche API-Leseberechtigungen:
- Jedes verbundene Konto verfügt über eine eigene Zuordnung für initiierte Anfragen (500 Anfragen pro Transaktion).
- Connect-Plattformen verwenden eine separate Zuweisung, um Leseanfragen im Namen ihrer verbundenen Konten durchzuführen, indem sie entweder ihren geheimen API-Schlüssel oder OAuth-Zugriffstoken verwenden. Diese Zuordnung beträgt ebenfalls 500 Anfragen pro Transaktion, basierend auf der aggregierten Transaktionsanzahl der verbundenen Konten.
- Quoten werden auf einer rollierenden 30-Tage-Basis gemessen.
- Jedem Konto, unabhängig von der Anzahl der Transaktionen, werden mindestens 10.000 Leseanfragen pro Monat zugewiesen.
- API-Schreibanfragen haben kein Zuordnungslimit.
Aufrufe der folgenden API-Endpoints sind von den obigen Zuordnungslimits ausgenommen:
Um Ihr API-Anfragevorlumen zu reduzieren, können Sie Stripe Data Pipeline für einen vollständigen Export der API-Daten in Ihre lokale Datenbank oder Ihren Anbieter verwenden.
Anfragen filtern, um paginierte Aufrufe zu begrenzen
Einige Listen-Endpoints geben mehrere Seiten mit Ergebnissen zurück und erfordern möglicherweise mehrere Anfragen, um den vollständigen Satz von API-Objekten für einen Listenvorgang zurückzugeben. Wenden Sie nach Möglichkeit Filter an, um Ihre Listenergebnisse einzugrenzen.