Limites de débit

Nous utilisons des mesures de protection contre les augmentations de trafic entrant pour optimiser la stabilité de l’API. Si vous envoyez plusieurs requêtes coup sur coup, vous pourriez recevoir des réponses d’erreur 429.

Limiteurs d’API

Nous appliquons plusieurs limiteurs API, notamment les limiteurs de débit et de concurrence. Traitez les limites comme des seuils maximums et évitez toute charge inutile. Pour éviter tout abus, nous pouvons réduire vos limites. Pour obtenir des conseils sur la gestion des erreurs 429, consultez la page Gestion appropriée des limites. Si vous constatez une hausse des requêtes à débit limité, contactez le service de support Stripe.

Demandez une augmentation du plafond pour les applications à fort trafic auprès du service de support Stripe. Si vous demandez une augmentation importante, contactez le service de support Stripe au moins 6 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
• Environnement de test : 25 opérations

Les appels à des ressources individuelles sont soumis à des limites plus strictes et sont également pris en compte dans les limites globales. Les endpoints 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.
• Abonnements API  :
  • 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.
• API Create Virement : 15 requêtes par seconde et 30 requêtes simultanées par marchand.
• Connect : les plateformes peuvent créer jusqu’à 5 comptes par seconde en environnement de test et 30 comptes par seconde en mode production.
• Issuing : la création de cartes bancaires est soumise à des limites de débit qui dépendent du pays et du secteur d’activité de l’entreprise.

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 1000 appels par seconde et par compte Stripe. Dans un environnement de test, les appels à l’endpoint Meter events sont comptabilisés dans la limite de base. Pour les plateformes Connect, les appels à l’endpoint Meter events effectués sur un compte connecté sont également pris en compte dans la limite de base.

Requêtes à débit limité

Les requêtes dont le débit est limité renvoient l’en-tête Stripe-Rate-Limited-Reason avec des valeurs qui indiquent la nature de la limite de débit dépassée par la requête. 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 simultanées. Vous pouvez éviter cette situation en envoyant moins de requêtes simultanées.
• global-rate : Vos requêtes ont dépassé la limite de débit globale. Vous pouvez éviter cette situation en envoyant des requêtes à un débit plus faible.
• endpoint-concurrency : Les requêtes que vous avez adressées à cet endpoint d’API ont dépassé la limite d’opérations simultanées. Vous pouvez éviter cette situation en envoyant moins de requêtes simultanées à cet endpoint.
• endpoint-rate : Les requêtes que vous envoyez à cet endpoint d’API ont dépassé la limite de débit. Vous pouvez éviter cette situation en envoyant des requêtes à cet endpoint à un débit plus faible.
• resource-specific : Vous avez atteint une limite d’appels liée à une ressource API spécifique. Pour en savoir plus, consultez la documentation sur cette ressource.

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

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 d’un grand nombre de requêtes de longue durée peut déclencher une limitation. Les requêtes varient en termes de quantité de ressources serveur Stripe utilisées, et les requêtes plus gourmandes en ressources peuvent prendre plus de temps et risquer de provoquer le rejet de nouvelles requêtes par le limiteur de concurrence. Les besoins en ressources varient considérablement, mais les requêtes de liste et celles incluant des extensions utilisent généralement plus de ressources et sont plus longues à exécuter. Nous vous suggérons de profiler la durée des requêtes API Stripe et de surveiller les délais d’expiration afin d’identifier les requêtes 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 de support Stripe.

Gérer la limitation

Surveillez les codes d’état 429 et mettez en œuvre un mécanisme de relance pour gérer la limitation du débit. Suivez un calendrier de retrait exponentiel pour réduire le volume de requêtes si nécessaire, et ajoutez de l’aléatoire au calendrier de retrait pour éviter un effet de thundering herd.

É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 API ou un autre processus Stripe l’utilise actuellement. Si vous rencontrez cette erreur ponctuellement, relancez 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. Stripe ne traite pas ces requêtes échouées, car l’ID de requête 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

Les utilisateurs ont l’habitude de se préparer à un événement commercial majeur en soumettant leurs systèmes à un test de charge dans le cadre duquel l’API Stripe est exécutée dans un environnement de test. Nous déconseillons généralement cette pratique, car les limites de l’API sont plus basses dans un environnement de test. Le test de charge risque donc d’atteindre des limites qu’il n’atteindrait pas en mode production. Le mode test n’est pas non plus un substitut idéal 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 entraîne l’envoi d’une requête à une plateforme de paiement. En mode test, cette requête est simulée et les profils de latence sont donc nettement 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 lues par votre compte ne doivent pas dépasser 500 en moyenne par transaction. Par exemple, si vous traitez 100 transactions en 30 jours, vous ne devez pas dépasser 50 000 requêtes API lues au cours de cette 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 calculés sur une période glissante de 30 jours (les 30 derniers 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.