Ratenbegrenzungen

Wir setzen Schutzmaßnahmen gegen sehr hohe Mengen von eingehendem Datenverkehr ein, um die höchstmögliche API-Stabilität zu gewährleisten. Wenn Sie viele Anfragen in schneller Folge senden, erhalten Sie möglicherweise 429-Fehlermeldungen.

API-Begrenzer

Wir setzen zwingend mehrere API-Begrenzer ein, einschließlich Raten- und Parallelitätsbegrenzer (Begrenzer für gleichzeitige Zugriffe). Behandeln Sie die Begrenzungen bitte als Höchstwerte und vermeiden Sie unnötige Belastungen. Um Missbrauch zu verhindern, können wir Ihre Begrenzungen reduzieren. Hinweise zum Umgang mit 429-Fehlern finden Sie unter Angemessener Umgang mit Begrenzungen. Falls Sie einen Anstieg der Anfragen mit Ratenbegrenzung feststellen, kontaktieren Sie den Stripe-Support.

Anfragen für eine Erhöhung der Begrenzung im Falle von Anwendungen mit hohem Datenverkehr richten Sie bitte an den Stripe-Support. Wenn Sie eine große Erhöhung anfordern, kontaktieren Sie den Stripe-Support mindestens 6 Wochen im Voraus.

Ratenbegrenzer

Die Basis-Ratenbegrenzung begrenzt die Anzahl der API-Anfragen pro Sekunde wie folgt:

• Live-Modus: 100 Vorgänge
• Sandbox: 25 Vorgänge

Aufrufe an einzelne Ressourcen haben strengere Grenzwerte und werden auch auf globale Grenzwerte angerechnet. Für API-Endpoints gilt standardmäßig ein Limit von 25 Anfragen pro Sekunde. Stripe kann die Ratenbegrenzungen für bestimmte Konten je nach Nutzung erhöhen.

• Payment Intents API: 1.000 Aktualisierungsvorgänge pro PaymentIntent und Stunde
• Files API: 20 Lesevorgänge und 20 Schreibvorgänge pro Sekunde.
• Search API: 20 Lesevorgänge pro Sekunde.
• Subscriptions API:
  • 10 neue Rechnungen pro Abo pro Minute
  • 20 neue Rechnungen pro Abo pro Tag
  • 200 Mengenaktualisierungen pro Abo pro Stunde
• Create Payout API: 15 Anfragen pro Sekunde und 30 gleichzeitige Anfragen pro Unternehmen.
• Connect: Plattformen können bis zu 5 Konten pro Sekunde in Sandbox und 30 Konten pro Sekunde im Live-Modus erstellen.
• Issuing: Für die Erstellung von Karten gelten Ratenbegrenzungen, die vom Land und der Branche des Unternehmens abhängen.

Aufrufe an den Endpoint für Zählerereignisse im Live-Modus unterliegen einer separaten Ratenbegrenzung und werden nicht auf die Grundbegrenzungen angerechnet. Das Limit beträgt 1.000 Aufrufe pro Sekunde pro Stripe-Konto. In einer Sandbox zählen die Aufrufe des Endpoints für Zählerereignisse zur Grundbegrenzung. Bei Connect-Plattformen zählen Aufrufe des Endpoints für Zählerereignisse durch ein verbundenes Konto ebenfalls zur Grundbegrenzung.

Anfragen mit Ratenbegrenzung

Anfragen mit Ratenbegrenzung geben den Header Stripe-Rate-Limited-Reason mit Werten zurück, die angeben, welche Ratenbegrenzung die Anfrage überschritten hat. Mögliche Werte für diesen Header sind:

• global-concurrency: Ihre Anfragen haben das globale Limit für Gleichzeitigkeit überschritten. Sie können dies verhindern, indem Sie weniger gleichzeitige Anfragen senden.
• global-rate: Ihre Anfragen haben die globale Ratenbegrenzung überschritten. Sie können dies verhindern, indem Sie Anfragen mit einer niedrigeren Rate senden.
• endpoint-concurrency: Ihre Anfragen an diesen speziellen API-Endpoint haben das Limit für die Gleichzeitigkeit überschritten. Sie können dies verhindern, indem Sie weniger gleichzeitige Anfragen an diesen speziellen Endpoint senden.
• endpoint-rate: Bei Ihren Anfragen an diesen speziellen API-Endpoint wurde die Ratenbegrenzung überschritten. Sie können dies verhindern, indem Sie Anfragen mit einer niedrigeren Rate an diesen Endpoint senden.
• resource-specific: Sie haben eine Ratenbegrenzung in Bezug auf eine bestimmte API-Ressource erreicht. Weitere Informationen finden Sie in der Dokumentation zu dieser Ressource.

Wenn eine Anfrage den Statuscode 429 ohne diese Header zurückgibt, war dies nicht das Ergebnis einer Ratenbegrenzung (zum Beispiel kann es sich um eine Zeitüberschreitung bei der Sperre handeln).

Parallelitätsbegrenzer (Begrenzer für gleichzeitige Zugriffe)

Der Parallelbegrenzer begrenzt die Anzahl der gleichzeitigen aktiven Anfragen. Probleme treten bei diesem Begrenzer seltener auf als bei dem Ratenbegrenzer. Es ist bei Ihnen aber wahrscheinlicher, dass es zu ressourcenintensiven, langlebigen Anfragen kommt.

Aufrufe an den Endpoint für Zählerereignisse sind auf einen gleichzeitigen Anruf pro Kundin/Kunde und Zähler beschränkt.

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 jedoch 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 (Blitzverkauf), kann zu einer Ratenbegrenzung führen. Wir versuchen, unsere Begrenzungsraten so hoch anzusetzen, dass es beim legitimen Zahlungsverkehr die Begrenzungen nie überschritten werden. Wenn Sie jedoch vermuten, dass ein bevorstehendes Ereignis dazu führen könnte, dass die obigen Begrenzungen überschritten werden, kontaktieren Sie bitte den Stripe-Support.

Umgang mit Begrenzungen

Achten Sie auf 429-Statuscodes und implementieren Sie einen Wiederholungsmechanismus zum Umgang mit Ratenbegrenzungen. Befolgen Sie einen exponentiellen Backoff-Zeitplan, um das Anfragenvolumen bei Bedarf zu reduzieren, und fügen Sie dem Backoff-Zeitplan den Faktor der Zufälligkeit hinzu, um einen Thundering Herd Effect (zu deutsch etwa „stampfender Herdeneffekt), zu vermeiden. (Dieser Begriff beschreibt eine Situation, in der eine große Anzahl von Prozessen oder Anfragen gleichzeitig auf eine Ressource zugreift, nachdem diese kurzzeitig nicht verfügbar war.)

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.

Sperrzeitüberschreitungen für Objekte

Bei Integrationen können Fehler mit dem HTTP-Status 429, dem 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-Vorgang darauf zugreift. Wenn dieser Fehler zeitweise angezeigt wird, wiederholen Sie die Anfrage. Wenn dieser Fehler häufig auftritt und Sie 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. Stripe verarbeitet diese fehlgeschlagenen Anfragen nicht, was bedeutet, dass ihnen keine Anfrage-ID zugewiesen wird.

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 SDKs von Stripe integrierten Wiederholungsmechanismen Versuche mit 429-Statuscodes, die durch Zeitüberschreitungen bei Sperren verursacht werden:

Stripe.max_network_retries = 2

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.

Belastungstests

Es ist üblich, dass sich Nutzer/innen auf ein wichtiges Verkaufsereignis vorbereiten, indem sie ihre Systeme einem Belastungstest unterziehen, bei dem die Stripe API in einer Sandbox ausgeführt wird. Wir raten im Allgemeinen von dieser Praxis ab, da die Grenzwerte für die API in einer Sandbox niedriger sind, sodass der Belastungstest wahrscheinlich auf Grenzwerte stößt, die er in der Produktion nicht erreichen würde. Eine Sandbox ist auch kein perfekter Ersatz für Live-Aufrufe der API, und dies kann etwas irreführend sein. Beispielsweise wird beim Erstellen einer Zahlung im Live-Modus eine Anfrage an ein Zahlungs-Gateway gesendet, die dann in einer Sandbox simuliert wird, was zu deutlich unterschiedlichen Latenzprofilen führt.

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 API-Leseanfragen Ihres Kontos dürfen durchschnittlich 500 pro Transaktion nicht überschreiten. Wenn Sie beispielsweise 100 Transaktionen in 30 Tagen verarbeiten, dürfen Sie in diesem Zeitraum die Anzahl von 50.000 API-Leseanfragen nicht überschreiten.

• 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.

• Die Kennzahlen werden über einen rollierenden Zeitraum von 30 Tagen (die letzten 30 Tage) berechnet.

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

• Datenprodukte
• Produkte zur Berichterstattung
• Steuerprodukte

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.