Limites de débit

L’API Stripe utilise différents mécanismes pour éviter les augmentations soudaines de trafic entrant qui risqueraient de nuire à leur stabilité. Si vous envoyez un nombre trop important de requêtes sur une courte période, vous pourriez ainsi être confronté à des erreurs avec le code d’état 429.

Les mécanismes de limitation d’API

Nous avons plusieurs mécanismes de limitation dans l’API, y compris un mécanisme de limitation de débit et un mécanisme de limitation d’opérations parallèles.

Considérez ces limites comme des maximums et ne générez pas de débit superflu. Nous pouvons réduire les limites pour éviter les abus.

Consultez la section Gestion appropriée des limites pour en savoir plus sur la gestion des codes d’état 429. Si vous constatez une hausse subite du nombre de requêtes concernées par la limitation du débit, contactez le service d’assistance Stripe.

Vous pouvez demander une augmentation de la limite pour activer une application à fort trafic en contactant le service d’assistance Stripe. Si votre demande porte sur une augmentation importante, contactez-nous au moins six semaines à l’avance.

Mécanisme de limitation de débit

Le mécanisme de limitation de débit de base restreint le nombre de requêtes d’API par seconde comme suit :

• Mode production : 100 opérations
• Bac à sable : 25 opérations

Les appels effectués à des ressources individuelles sont soumis à des limites plus strictes et sont également pris en compte dans les limites globales. Les points de terminaison d’API sont limités par défaut à 25 requêtes par seconde. Stripe peut augmenter les limites de débit pour certains comptes en fonction de leur utilisation.

• Files API : 20 opérations de lecture et 20 opérations d’écriture par seconde
• Search API : 20 opérations de lecture par seconde

Les appels effectués au point de terminaison d’événements de compteur en mode production sont soumis à une limite de débit distincte et ne sont pas pris en compte dans les limites standards. La limite est de 1 000 appels par seconde par compte Stripe. Dans un bac à sable, les appels au point de terminaison d’événements de compteurs sont pris en compte dans la limite standard. Pour les plateformes Connect, les appels effectués d’un compte connecté au point de terminaison d’événements de compteur sont également pris en compte dans la limite standard.

Requêtes soumises à une limite

Les requêtes dont le débit est limité renvoient l’en-tête Stripe-Rate-Limited-Reason avec des valeurs qui indiquent la limite de débit dépassée par la demande. Les valeurs possibles pour cet en-tête sont les suivantes :

• global-concurrency : Vos requêtes ont dépassé la limite globale d’opérations parallèles. Vous pouvez éviter cette situation en envoyant moins de requêtes simultanées.
• global-rate : Vos requêtes ont dépassé la limite globale. Vous pouvez éviter cette situation en envoyant des requêtes à un débit plus faible.
• endpoint-concurrency : Les requêtes que vous avez envoyées à ce point de terminaison d’API ont dépassé la limite d’opérations parallèles. Vous pouvez éviter cette situation en envoyant moins de requêtes simultanées à ce point de terminaison spécifique.
• endpoint-rate : Les requêtes que vous envoyez à ce point de terminaison d’API ont dépassé la limite de débit. Vous pouvez éviter cette situation en envoyant des requêtes à ce point de terminaison à un débit plus faible.
• resource-specific : Vous avez atteint une limite de débit liée à une ressource d’API spécifique. Pour obtenir plus d’informations, consultez la documentation de cette ressource.

Si une requête renvoie un code d’état 429 sans ces en-têtes, il ne s’agit pas du résultat d’un mécanisme de limitation de débit (par exemple, il peut s’agir d’un délai d’expiration du verrouillage).

Mécanisme de limitation d’opérations parallèles

Le mécanisme de limitation d’opérations parallèles restreint le nombre de requêtes actives en parallèle. Les problèmes liés à ce mécanisme sont moins fréquents que ceux liés au mécanisme de limitation de débit, mais ils indiquent l’existence potentielle de requêtes longues et qui exigent des ressources considérables.

Les appels effectués au point de terminaison des événements de compteur sont limités à un appel simultané par client et par compteur.

Causes de limitation fréquentes et solutions

La limitation du débit peut se produire pour diverses raisons, mais les scénarios ci-dessous sont les plus courants :

• L’exécution d’un grand nombre de requêtes à des intervalles resserrés peut entraîner une limitation du débit. Cette situation survient souvent dans le cadre d’une opération d’analyse ou de migration. Lorsque vous lancez une telle activité, essayez de gérer le nombre de requêtes côté client (voir Gestion appropriée des limites).
• L’émission de nombreuses requêtes longues peut déclencher la limitation. Les requêtes n’utilisent pas toutes la même quantité de ressources sur les serveurs de Stripe. Les requêtes plus gourmandes tendent à durer plus longtemps et risquent d’entraîner le rejet d’autres requêtes par le limiteur d’opérations parallèles. Les exigences en matière de ressources sont très variables, mais les requêtes de listes et les requêtes qui incluent des extensions sont généralement plus gourmandes et prennent plus de temps. Nous vous suggérons d’analyser la durée des requêtes envoyées aux API Stripe et de surveiller d’éventuelles expirations pour déterminer quelles requêtes sont anormalement lentes.
• Une hausse soudaine du débit, comme dans le cas d’un solde-éclair, peut entraîner la limitation du débit. Nous essayons de fixer nos limites à un niveau suffisamment élevé pour que le trafic de paiement légimite ne dépasse jamais les limites. Toutefois, si vous craignez qu’un événement n’entraîne un dépassement de ces limites, veuillez contacter le service d’assistance Stripe.

Gestion appropriée des limites

Il existe un moyen simple de faire en sorte que les intégrations gèrent de manière appropriée les limites : surveiller les codes d’état 429 et inclure un mécanisme permettant de relancer les requêtes. Ce mécanisme doit respecter un délai d’attente qui augmente de manière exponentielle lorsque cela est nécessaire. Nous recommandons également d’y intégrer un aspect aléatoire pour éviter tout effet de réaction de masse.

Étant donné que vous ne pouvez optimiser chaque requête que dans une mesure limitée, vous pouvez aborder le problème de façon plus élégante en contrôlant le trafic émis vers Stripe de manière globale et en le restreignant lorsque vous détectez une limitation de débit significative. Un algorithme de type seau à jetons côté client est fréquemment utilisé à cet effet. Il existe des implémentations prêtes à l’emploi et tout à fait matures de cet algorithme pour la quasi-totalité des langages de programmation.

Expirations du verrouillage d’objets

Les intégrations peuvent rencontrer des erreurs avec l’état HTTP 429, le code lock_timeout, et le message suivant :

Cet objet n’est pas accessible pour le moment, car une autre requête d’API ou un autre processus Stripe l’utilise actuellement. Si vous rencontrez cette erreur ponctuellement, soumettez de nouveau votre requête. Si vous rencontrez fréquemment cette erreur et que vous soumettez plusieurs requêtes simultanées pour un même objet, soumettez-les en série ou à une fréquence moindre.

L’API de Stripe verrouille des objets lors de certaines opérations pour éviter toute interférence par des charges de travail parallèles et la génération d’un résultat incohérent. L’erreur ci-dessus est causée par une requête qui essaie de verrouiller un objet déjà verrouillé et qui expire, car l’opération n’a pas abouti dans les délais.

Les délais de verrouillage n’ont pas les mêmes causes que la limitation du débit, mais les solutions à ces deux phénomènes sont similaires. Comme pour les erreurs liées à la limitation du débit, nous vous recommandons de relancer la requête selon des intervalles exponentiels (consultez la section sur Gestion appropriée des limites). Toutefois, les mécanismes automatiques intégrés dans les trousses SDK de Stripe relancent les requêtes générant un code 429 causé par l’expiration d’un verrouillage, mais non celles générant une erreur liée à la limitation du débit :

Stripe.max_network_retries = 2

Les conflits de verrouillage sont causés par des accès simultanés à des objets liés. Les intégrations peuvent fortement réduire ce problème en s’assurant que les mutations sur un même objet sont mises en file d’attente et exécutées de manière séquentielle. Les opérations parallèles sur les API sont acceptées, mais essayez de vous assurer que ce type d’opération ne concerne que des objets uniques. Il est également possible qu’un conflit de verrouillage soit lié à un processus Stripe exécuté en arrière-plan. Ce type de situation ne se produit que rarement, mais l’utilisateur n’a alors aucune solution. Nous recommandons de faire en sorte que toutes les intégrations puissent relancer les requêtes.

Test de charge

Il est courant que les utilisateurs se préparent à un événement commercial d’envergure en effectuant des tests de charge de leurs systèmes avec l’API Stripe étant exécutée dans un bac à sable. Nous déconseillons généralement cette pratique, car les limites de l’API sont plus basses dans un bac à sable : le test de charge risque donc d’atteindre des limites qu’il n’atteindrait pas en mode production. Par ailleurs, le bac à sable n’est pas un substitut idéal au mode production en matière d’appels à l’API, ce qui peut être trompeur. Par exemple, la création d’un paiement en mode production envoie une requête à une passerelle de paiement. Dans un bac à sable, cette requête est simulée et les profils de latence sont alors très différents.

Nous vous recommandons de développer vos intégrations de sorte qu’elles disposent d’un système configurable de simulation de requêtes à l’API de Stripe que vous pouvez activer lors des tests de charge. Pour obtenir des résultats réalistes, il doit simuler une latence en patientant pendant un délai que vous déterminez après avoir échantillonné la durée d’appels aux API de Stripe en mode production du point de vue de l’intégration.

Allocations de requête de lecture d’API

Stripe donne accès à ses requêtes d’API de lecture (GET) pour faciliter les activités de recherche raisonnable liée aux intégrations de paiement. Afin de maximiser la qualité de service pour tous les utilisateurs, Stripe fournit les allocations suivantes pour les requêtes de lecture en fonction du nombre de transactions :

• Les requêtes de lecture d’API ne doivent pas dépasser un ratio moyen de 500 demandes par transaction pour un compte. Par exemple, si un compte traite 100 transactions au cours d’une période de 30 jours, il ne doit pas dépasser 50 000 requêtes d’API lues au cours de la même période.
• Lors de l’utilisation de Connect, une plateforme et ses comptes connectés disposent d’autorisations de lecture d’API distinctes :
  • Chaque compte connecté dispose de sa propre allocation pour les requêtes initiées (500 requêtes par transaction).
  • Les plateformes Connect utilisent une allocation distincte pour effectuer des requêtes de lecture au nom de leurs comptes connectés à l’aide de leur clé API secrète ou de jetons d’accès OAuth. Cette allocation est également de 500 demandes par transaction en fonction du nombre total de transactions sur ses comptes connectés.
• Les ratios sont mesurés sur une base continue de 30 jours.
• Chaque compte, quel que soit le nombre de transactions, dispose d’une allocation minimale de 10 000 requêtes de lecture par mois.
• Les requêtes d’écriture d’API n’ont pas de limite d’allocation.

Les appels vers les points de terminaison API suivants sont exclus des limites d’allocation ci-dessus :

• Produits de données
• Rapports sur les produits
• Produits fiscaux

Pour réduire le volume de vos requêtes d’API, envisagez d’utiliser Stripe Data Pipeline pour exporter complètement les données d’API vers votre base de données ou votre fournisseur local.