Limites de débit
L’API Stripe utilise plusieurs dispositifs de protection contre les augmentations de trafic entrant pour assurer une stabilité optimale. Les utilisateurs qui envoient plusieurs requêtes successives sur une courte période peuvent voir apparaître des messages d’erreur indiquant le code d’état 429
. Ces dispositifs de limitation du débit de l’API incluent :
Un limiteur de débit, qui restreint le nombre de requêtes reçues par seconde par les API.
Pour la plupart des API, Stripe autorise en mode production jusqu’à 100 opérations par seconde en lecture et en écriture, contre 25 opérations en mode test.
Pour l’API Files, Stripe autorise jusqu’à 20 opérations par seconde en lecture et en écriture, que ce soit en mode. Les limites du mode production et du mode test sont les mêmes, mais les opérations sont comptabilisées distinctement dans chaque mode.
Pour l’API Search, Stripe autorise jusqu’à 20 opérations par seconde en lecture, lesquelles s’appliquent à tous les points de terminaison de recherche, en mode production comme en mode de test. Ces deux modes ont des limites distinctes.
Un limiteur d’opérations parallèles, qui restreint le nombre de requêtes actives en parallèle. Ce mécanisme pose moins de difficultés que le limiteur de débit, mais il a plus de chances d’aboutir à des requêtes longues et gourmandes en ressources.
Considérez ces limites comme des maximums et ne générez pas de charge superflue. 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.
Nous pouvons réduire les limites pour éviter les abus ou les augmenter pour permettre l’exécution d’applications à fort trafic. Pour demander une augmentation de votre limite de débit, veuillez contacter le service d’assistance. Si votre demande porte sur une augmentation importante, contactez-nous six semaines avant la date à laquelle vous aurez besoin de cette augmentation.
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’une vente-éclair, peut aboutir au déclenchement de la limitation du débit. Nous essayons de fixer nos limites suffisamment haut pour éviter à la majorité des utilisateurs de voir son trafic de paiement limité. Toutefois, si vous craignez qu’un événement n’entraîne un dépassement de ces limites, veuillez contacter le service d’assistance.
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 (voir Gestion appropriée des limites). Toutefois, les mécanismes automatiques intégrés dans les bibliothèques côté client relancent les requêtes générant un code 429
causé par l’expiration d’un verrouillage, mais pas celles générant une erreur liée à la limitation du débit :
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 décourageons toutefois 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 ainsi ê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 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 :
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.
Filtrer les requêtes pour limiter les appels paginés
Certains points de terminaison de liste renvoient plusieurs pages de résultats et peuvent nécessiter plusieurs requêtes pour renvoyer l’ensemble complet des objets API pour une opération de liste. Appliquez des filtres lorsque cela est possible pour affiner les résultats de votre liste.