Limites de débit

Nous utilisons des mesures de protection contre les augmentations soudaines de trafic entrant pour maximiser la stabilité de l’API. Si vous envoyez plusieurs requêtes sur une courte période, vous pourriez être confronté à des réponses d’erreurs avec le code 429.

Les mécanismes de limitation d’API

Nous appliquons plusieurs limiteurs API, notamment des limiteurs de débit et de concurrence. Considérez ces limites comme des maximums et évitez toute charge inutile. Pour prévenir tout abus, nous pouvons être amenés à réduire vos limites. Pour obtenir des conseils sur la gestion des erreurs 429, consultez la section Gestion élégante des limites. Si vous constatez une augmentation des requêtes soumises à la limite contactez le service d’assistance Stripe.

Demandez une augmentation de la limite pour les applications à fort trafic par l’entremise du service d’assistance Stripe. Si vous demandez une augmentation importante, contactez le service d’assistance Stripe au moins 6 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.

• API Payment Intents : 1 000 opérations de mise à jour par PaymentIntent, par heure
• API Files : 20 opérations de lecture et 20 opérations d’écriture par seconde.
• API Search : 20 opérations de lecture par seconde.
• API d’abonnements :
  • 10 nouvelles factures par abonnement et par minute.
  • 20 nouvelles factures par abonnement et par jour.
  • 200 mises à jour de quantité par abonnement et par heure
• Créez l’API Payout : 15 requêtes par seconde et 30 requêtes par marchand simultanées.
• Connect : les plateformes peuvent créer jusqu’à 5 comptes par seconde en bac à sable et 30 comptes par seconde en mode production.
• Issuing : La création de cartes est soumise à des limites de débit qui dépendent du pays et du secteur d’activité de l’entreprise.

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.

Demandes soumises à la 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égitime ne dépasse jamais les limites. Toutefois, si vous craignez qu’un événement à venir puisse vous faire dépasser les limites indiquées ci-dessus, veuillez contacter le service d’assistance Stripe.

Gérer la limitation

Surveillez les codes d’état 429 et mettez en place un mécanisme de relance pour gérer la limitation du débit. Respectez un calendrier de retrait exponentiel pour réduire le volume de requêtes lorsque cela est nécessaire, et ajoutez un aspect aléatoire au calendrier de retrait pour éviter un 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 afin que les charges de travail concurrentes n’interfèrent pas et ne produisent des résultats incohérents. L’erreur ci-dessus est causée par une requête qui tente d’acquérir un verrou déjà bloqué ailleurs et qui expire après avoir échoué à l’acquérir à temps. Stripe ne traite pas ces requêtes ayant échoué, ce qui signifie qu’aucun identifiant de requête ne leur est attribué.

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é à une procédure 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 de votre compte ne doivent pas dépasser une moyenne de 500 par transaction. Par exemple, si vous traitez 100 transactions en 30 jours, vous ne devez pas dépasser 50 000 requêtes de lecture d’API pendant cette 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 calculés sur une période glissante de 30 jours (les 30 derniers 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.