Limites de débit

L’API Stripe utilise plusieurs dispositifs de protection contre les augmentations de trafic entrant pour assurer une stabilité optimale. Si vous envoyez plusieurs requêtes successives sur une courte période, des messages d’erreur avec le code d’état 429 peuvent apparaître.

Limiteurs d’API

Il existe plusieurs limiteurs dans l’API, tels qu’un limiteur de débit et un limiteur d’opérations simultanées.

Considérez ces limites comme des maximums et ne générez pas de charge superflue. Afin de prévenir les abus, nous pourrions réduire les limites.

Pour en savoir plus sur la gestion des erreurs avec le code d’état 429, consultez la section Gestion appropriée des limites. Si vous constatez une hausse subite du nombre de requêtes de limitation du débit, contactez le service d’assistance Stripe.

Vous pouvez demander une hausse de la limite pour permettre l’exécution d’applications à fort trafic en contactant le service d’assistance Stripe. Si votre demande porte sur une hausse substantielle, contactez-nous au moins six semaines à l’avance.

Limiteur de débit

Le limiteur de débit de base restreint le nombre de requêtes reçues par seconde par l’API comme suit :

• Mode production : 100 opérations de lecture et 100 opérations d’écriture
• Mode test : 25 opérations de lecture et 25 opérations d’écriture

Les appels à certaines ressources sont soumis à des limites plus strictes et sont également pris en compte dans les limites de base. Ces limites plus strictes s’appliquent séparément dans le mode production et dans le mode test.

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

Les appels à l’endpoint Meter events en mode production sont soumis à une limite de débit distincte et ne sont pas pris en compte dans les limites de base. La limite est de 1 000 appels par seconde et par compte Stripe. En mode test, les appels à l’endpoint Meter events sont pris en compte dans la limite de base. Pour les plateformes Connect, les appels sur un compte connecté à l’endpoint Meter events sont également pris en compte dans la limite de base.

Limiteur d’opérations simultanées

Le limiteur d’opérations simultanées limite le nombre de requêtes actives au même moment. Les problèmes liés à ce limiteur sont moins fréquents que ceux liés au limiteur de débit, mais ils indiquent généralement l’existence de requêtes longues et exigeantes en ressources.

Les appels à l’endpoint Meter Events sont limités à un appel simultané par client et par mesure.

Causes de limitation fréquentes et solutions

La limitation du débit peut intervenir pour diverses raisons, mais les scénarios suivants 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’une vente flash, peut entraîner le déclenchement de la limitation du débit. Nous essayons de fixer nos limites suffisamment haut pour que le trafic des paiements légitimes ne soit jamais dépassé. Toutefois, si vous craignez qu’un événement entraîne un dépassement de ces limites, 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 associées à l’état 429, au code lock_timeout et au message :

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, resoumettez votre requête. Si vous la rencontrez fréquemment 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 expirations des verrouillages 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 Gestion appropriée des limites). Toutefois, les mécanismes automatiques intégrés dans les SDK de Stripe relancent les requêtes aboutissant à un code 429 causé par l’expiration d’un verrouillage, mais pas celles aboutissant à 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 pour les utilisateurs de préparer leurs campagnes de vente d’envergure en procédant à un test de charge de leurs systèmes avec les API de Stripe en mode test. Nous ne recommandons toutefois pas cette pratique, car les limites des API sont plus basses en mode test : le test de charge risque donc de rencontrer des limites que l’intégration n’atteindra pas en mode production. Par ailleurs, le mode test n’est pas parfaitement équivalent au mode production en matière d’appel aux API, ce qui peut donc être trompeur. Par exemple, la création d’un paiement en mode production envoie une requête à une passerelle de paiement. En mode test, cette requête est simulée et les profils de latence sont donc 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 Stripe pouvant être activé 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.

Affectation des requêtes de lecture API

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

• Les requêtes API de lecture ne doivent pas dépasser un ratio moyen de 500 requêtes par transaction pour un compte. Par exemple, si un compte traite 100 transactions sur une période de 30 jours, elles ne doivent pas dépasser 50 000 requêtes API de lecture au cours de cette même période.
• Lors de l’utilisation de Connect, une plateforme et ses comptes connectés disposent de quotas d’API de lecture distincts :
  • Chaque compte connecté dispose de sa propre affectation pour les requêtes qu’il initie (500 requêtes par transaction).
  • Les plateformes Connect utilisent une affectation 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 affectation est également de 500 requêtes par transaction, sur la base du nombre total de transactions effectuées sur ses comptes connectés.
• Les ratios sont évalués sur une base régulière de 30 jours.
• Chaque compte, quel que soit son nombre de transactions, dispose d’une affectation minimale de 10 000 requêtes de lecture par mois.
• Les requêtes API d’écriture n’ont pas de limite d’affectation.

Les appels aux endpoints d’API suivants sont exclus des limites d’affectation ci-dessus :

• Produits de données
• Produits de rapports
• Produits fiscaux

Pour réduire votre volume de requêtes API, envisagez d’utiliser Stripe Data Pipeline pour une exportation complète des données API vers votre base de données ou fournisseur local.