Limites de débit et quotas autour desquels les partenaires peuvent concevoir

Un partenaire livre une intégration le vendredi, le trafic grimpe le week-end, et le lundi son app commence à se faire rejeter sans avertissement et sans indice sur le temps d'attente. Il n'a rien fait de mal. Votre API a simplement atteint une limite qu'il ne pouvait pas voir et qu'il ne pouvait pas anticiper. Le rate limiting n'est pas le méchant de cette histoire. Les en-têtes manquants, les rejets silencieux, et la limite que personne n'a documentée le sont. Une bonne limite est une limite autour de laquelle un partenaire peut concevoir avant même de l'atteindre, et la différence entre les deux est surtout de l'ingénierie que vous contrôlez.

Ceci est un guide indépendant du rate limiting pour une API sur laquelle les partenaires construisent. Il est écrit du côté de l'équipe qui fait tourner l'API, le producteur, parce que c'est là que se prennent les choix qui aident ou nuisent aux partenaires. Les spécificités d'une plateforme donnée changent, et les bons chiffres dépendent de votre infrastructure et de votre trafic, alors traitez les figures ici comme des illustrations plutôt que des recommandations. Ce qui ne change pas, c'est la forme du travail : choisir une stratégie de limite, renvoyer les en-têtes qui rendent la limite visible, donner aux clients un moyen clair de reculer, structurer les quotas par palier, et tout communiquer pour qu'un partenaire puisse planifier. C'est cette forme que ce guide couvre.

Il va de pair avec notre guide d'une API partner-ready, notre décryptage de la conception des erreurs d'API, et notre comparaison webhooks vs polling, puisque la pression du polling et les limites de débit sont les deux faces de la même question de charge.

L'essentiel en 60 secondes

• Le rate limiting protège tout le monde, y compris les partenaires. Une limite empêche un client bruyant de dégrader l'API pour les autres, ce qui est un service rendu aux partenaires qui se comportent bien.
• Choisissez une stratégie qui correspond à votre trafic. Fenêtres fixes, fenêtres glissantes et token buckets se comportent différemment en cas de pics. Choisissez celle qui correspond à la façon dont vos partenaires vous appellent réellement.
• Rendez la limite visible dans chaque réponse. Renvoyez des en-têtes qui disent quelle est la limite, combien il en reste, et quand elle se réinitialise, pour qu'un client se règle au lieu de deviner.
• Dites aux clients comment reculer. Un 429 avec un signal de retry clair transforme un rejet en un poli « réessayez dans N secondes » plutôt qu'un mur.
• Structurez les quotas par palier, pas un seul chiffre pour tous. Différents partenaires ont différents besoins, et un modèle par palier vous laisse dire oui à l'échelle sans dire oui à l'abus.
• Communiquez les limites avant que les partenaires ne les atteignent. Documentez les chiffres, les en-têtes et le comportement de backoff, pour que la limite soit une contrainte de conception, pas une surprise.
• Concevez pour une dégradation gracieuse. Quand un partenaire approche d'une limite, les meilleures API le ralentissent de façon prévisible plutôt que de le couper sans avertissement.

Pourquoi le rate limiting aide les partenaires, pas seulement vous

Il est facile de présenter le rate limiting comme l'API qui se protège des partenaires. Ce cadrage est à l'envers, et il mène à des limites qui paraissent adverses. Une limite de débit est la façon dont l'API protège chaque partenaire bien élevé du seul client qui, à cause d'un bug ou d'une boucle emballée, consommerait sinon toute la capacité et dégraderait le service pour tous les autres. Le partenaire dont l'intégration continue de marcher pendant l'incident de quelqu'un d'autre est celui que votre limite vient de protéger.

Ce recadrage compte parce qu'il change la façon dont vous concevez la limite. Si l'objectif est de punir l'usage intensif, vous construisez un mur grossier et un partenaire le percute sans avertissement. Si l'objectif est un partage équitable d'une ressource finie, vous construisez une limite visible, prévisible, et accompagnée de l'information dont un client a besoin pour rester en dessous. Le même chiffre peut être l'un ou l'autre, selon que vous l'exposez ou non. Le travail dans ce guide consiste surtout à rendre une limite nécessaire perçue comme équitable, parce qu'une limite équitable est une limite autour de laquelle les partenaires conçoivent au lieu de la combattre.

Il y a aussi un argument de fiabilité. Une API sans limites est une API qu'un mauvais client peut faire tomber, ce qui signifie une panne pour chaque partenaire d'un coup. Une limite sensée est une fonctionnalité de stabilité, et la stabilité est ce que les partenaires valorisent le plus dans quelque chose sur quoi ils ont bâti un produit. La limite n'est pas le coût de l'intégration avec vous. Elle fait partie de ce qui rend l'intégration avec vous sûre.

Étape 1 : choisir une stratégie de limite

La première décision est l'algorithme, parce que différentes stratégies se comportent très différemment sous le trafic en pics et inégal que génèrent de vrais partenaires. L'erreur courante est de choisir la plus simple sans réfléchir à la façon dont les partenaires appellent réellement l'API, puis de découvrir qu'elle rejette des pics légitimes ou laisse passer des flots qu'elle aurait dû attraper. Adaptez la stratégie à votre trafic.

Les trois approches dont la plupart des API partent :

Fenêtre fixe. Compter les requêtes dans un intervalle d'horloge fixe, disons par minute, et rejeter tout ce qui dépasse la limite jusqu'à ce que la fenêtre bascule. C'est la plus simple à implémenter et la plus facile à expliquer, ce qui fait son attrait. Sa faiblesse est la frontière : un client peut envoyer une fenêtre entière de requêtes à la fin d'une minute et une autre fenêtre entière au début de la suivante, doublant brièvement le débit prévu juste au bord.

Fenêtre glissante. Suivre les requêtes sur un intervalle roulant plutôt qu'une frontière d'horloge fixe, pour que la limite s'applique aux « 60 dernières secondes » à tout moment plutôt qu'à « cette minute du calendrier ». Cela lisse le problème de frontière de la fenêtre fixe au prix d'une comptabilité plus lourde. C'est un bon défaut quand les pics aux bords de fenêtre causent de vraies montées de charge.

Token bucket. Remplir un seau de jetons à un débit constant, dépenser un jeton par requête, et rejeter quand le seau est vide. Il autorise de courts pics jusqu'à la taille du seau tout en imposant un débit moyen soutenu dans le temps, ce qui correspond souvent bien à l'usage réel : les partenaires sont calmes, puis font un pic de travail, puis redeviennent calmes. Le token bucket est indulgent face aux pics légitimes tout en plafonnant l'abus soutenu.

Une façon rapide de choisir :

Quel que soit votre choix, appliquez la limite par partenaire ou par identifiant, pas globalement à travers tous. Une seule limite globale signifie qu'un partenaire occupé peut affamer tous les autres, ce qui est exactement l'échec que le rate limiting est censé prévenir. Restreignez la limite à l'identifiant pour que chaque partenaire ait sa propre part équitable.

Étape 2 : renvoyer les en-têtes qui rendent la limite visible

Une limite qu'un client ne peut pas voir est une limite qu'un client atteindra. La chose à plus fort effet de levier que vous puissiez faire pour les partenaires est de mettre l'état de leur limite dans chaque réponse, pour qu'un client bien écrit se règle et ne déclenche jamais un rejet en premier lieu. C'est la différence entre une limite qui surprend les partenaires et une autour de laquelle ils conçoivent, et cela vous coûte quelques en-têtes.

Il existe une convention largement utilisée pour cela. Sur chaque réponse, renvoyez combien de requêtes le client est autorisé dans la fenêtre courante, combien il en reste, et quand la fenêtre se réinitialise :

Les noms exacts des en-têtes varient selon la plateforme, et certaines API utilisent une variante préfixée X- des trois mêmes valeurs, alors documentez celle que vous choisissez. Ce qui compte, c'est que les trois informations soient présentes sur les réponses normales, pas seulement sur le rejet. Un client qui peut lire le restant et le reset sur un appel réussi peut se ralentir à l'approche de la limite, en étalant le travail au lieu de foncer dans le mur et de rebondir dessus.

Quand le client franchit la ligne, le bon code de statut est 429, « Too Many Requests », qui existe exactement pour ce cas. Associez-le à un signal clair du temps d'attente, couvert ensuite. Le principe est le même que dans nos recommandations sur la conception des erreurs d'API : une erreur devrait dire au client ce qui s'est passé et quoi faire, et un 429 avec un signal de retry fait les deux. Un 429 nu sans en-têtes dit au client seulement qu'il a échoué, ce qui le laisse deviner, et les clients qui devinent retentent trop vite et empirent le problème.

Étape 3 : dire aux clients comment reculer

Renvoyer un 429 n'est que la moitié du travail. L'autre moitié est de dire au client quand réessayer, parce qu'un rejet sans temps d'attente invite la pire réponse possible : un retry immédiat, puis un autre, martelant une API qui signale déjà qu'elle est à capacité. Le comportement de backoff vers lequel vous orientez les clients est ce qui sépare une limite qui se rétablit gracieusement d'une qui se transforme en tempête de retries.

Le signal le plus clair est l'en-tête Retry-After sur une réponse 429, qui dit au client exactement combien de secondes attendre avant de réessayer. Quand vous pouvez le calculer, envoyez-le, parce qu'il retire toute incertitude : le client attend le temps indiqué et réessaie une fois. C'est la chose la plus favorable aux partenaires qu'un endpoint sous limite puisse faire, et c'est peu coûteux à ajouter.

Quand vous ne pouvez pas donner un temps exact, orientez les clients vers un backoff exponentiel avec jitter :

• Le backoff exponentiel signifie que chaque retry attend plus longtemps que le précédent, disons une seconde, puis deux, puis quatre, pour qu'un client sous limite recule progressivement au lieu de réessayer à un intervalle fixe et rapide.
• Le jitter signifie ajouter un petit montant aléatoire à chaque attente, pour qu'un millier de clients tous limités au même instant ne réessaient pas tous au même instant. Sans jitter, des retries synchronisés créent un effet de troupeau qui re-déclenche la limite au moment où elle se lève.
• Un plafond de retries signifie abandonner après un nombre sensé de tentatives et faire remonter l'échec, plutôt que de réessayer indéfiniment. Un client coincé dans une boucle de retry infinie est un client qui génère de la charge sans chemin vers le succès.

Un flux de backoff simple à suivre pour un client :

Vous ne pouvez pas forcer les partenaires à implémenter cela, mais vous pouvez en faire le chemin évident en renvoyant Retry-After, en documentant le backoff que vous attendez, et idéalement en l'embarquant dans tout SDK que vous fournissez pour que le bon comportement soit le défaut. Un SDK qui gère le backoff correctement signifie que la plupart des partenaires l'obtiennent gratuitement, ce qui est la même logique que nos recommandations sur l'API partner-ready : le producteur rend la bonne chose facile.

Étape 4 : structurer les quotas par palier

Une seule limite de débit appliquée à chaque partenaire est un compromis qui ne convient à aucun : trop basse pour le partenaire qui fait du volume réel, trop haute pour le compte d'essai en qui vous n'avez pas encore confiance. Les quotas par palier résolvent cela en adaptant la limite à la relation, pour que vous puissiez accorder l'échelle aux partenaires qui l'ont méritée sans exposer l'API à l'abus de comptes dont vous ne savez rien.

L'idée est de définir un petit nombre de paliers, chacun avec ses propres limites, et d'assigner les partenaires à un palier selon leur plan, leur stade ou leur historique :

Quelques principes gardent un modèle par palier honnête. Rendez les paliers et leurs limites publics là où c'est pertinent, pour qu'un partenaire puisse voir ce que monter en gamme lui apporte et planifier une migration avant de dépasser le palier courant. Donnez aux partenaires un chemin clair vers un palier supérieur, que ce soit en passant à un plan supérieur ou en demandant une augmentation, parce qu'un partenaire qui ne peut pas grandir sur votre API finira par construire autour ou partir. Et séparez la limite de débit (requêtes par unité de temps) de tout quota sur fenêtre plus longue (requêtes par jour ou par mois) si vous utilisez les deux, parce qu'ils répondent à des questions différentes et qu'un partenaire a besoin de voir les deux pour planifier sa capacité.

La logique de palier est la même que celle derrière les paliers de programme partenaire : un palier est une façon d'offrir plus aux partenaires qui ont démontré qu'ils en feront bon usage, tout en gardant un défaut sensé pour les autres. La limite n'est pas qu'un contrôle technique. Elle fait partie de la relation commerciale, et la traiter ainsi vous laisse dire oui à la croissance délibérément.

Étape 5 : communiquer les limites avant que les partenaires ne les atteignent

La meilleure limite de débit au monde échoue auprès de ses partenaires s'ils la découvrent en l'atteignant. Tout dans les étapes précédentes, la stratégie, les en-têtes, le backoff, les paliers, n'aide qu'un partenaire qui sait qu'elle existe avant de livrer. La communication n'est pas la dernière étape boulonnée après l'ingénierie. C'est ce qui transforme l'ingénierie en quelque chose autour de quoi un partenaire peut concevoir.

Ce qu'inclut une communication claire des limites :

• Les chiffres, dans la doc. Énoncez les limites réelles pour chaque palier, la fenêtre sur laquelle elles s'appliquent, et tout quota journalier ou mensuel séparé. Un partenaire qui dimensionne une intégration a besoin des vrais chiffres, pas d'un « usage raisonnable ».
• Les en-têtes, expliqués. Documentez les noms exacts des en-têtes que vous renvoyez, ce que chacun signifie, et le fait qu'ils apparaissent sur les réponses normales, pour que les partenaires construisent des clients qui les lisent et les respectent.
• Le backoff que vous attendez. Dites aux partenaires d'honorer Retry-After, d'utiliser un backoff exponentiel avec jitter sinon, et de plafonner leurs retries. L'épeler vous donne des clients mieux élevés.
• À quoi ressemble un 429. Montrez la réponse exacte qu'un client reçoit quand il est limité, code de statut et en-têtes compris, pour que les partenaires la gèrent correctement du premier coup.
• Comment demander plus. Donnez aux partenaires un chemin clair vers un palier supérieur ou une augmentation temporaire pour un événement de trafic connu, pour qu'un lancement ne se transforme pas en mur.
• Préavis des changements. Si vous resserrez une limite, prévenez les partenaires avant qu'elle ne prenne effet, comme vous le feriez pour tout changement cassant, parce qu'un changement de limite peut casser une intégration qui marchait.

C'est la même discipline que bien documenter les erreurs, que nous couvrons dans la conception des erreurs d'API : le comportement qu'un client doit gérer devrait être écrit avant que le client ne le rencontre. Un partenaire qui lit vos limites, construit un client qui lit vos en-têtes et recule correctement, et choisit le bon palier atteindra rarement un rejet dur. C'est l'objectif. La limite existe toujours et protège toujours le service, mais elle est devenue une contrainte de conception que le partenaire a planifiée plutôt qu'un incident qu'il a percuté.

Erreurs fréquentes, et comment les corriger

Traiter la limite comme un mur au lieu d'un signal. Le correctif : renvoyez la limite, le compte restant et le temps de reset sur chaque réponse, pour que les clients se règlent avant d'atteindre le plafond. Une limite visible est une limite autour de laquelle les partenaires conçoivent ; une limite invisible en est une qu'ils percutent.

Renvoyer un 429 nu sans indication de retry. Le correctif : envoyez Retry-After quand vous pouvez le calculer, et documentez le backoff exponentiel avec jitter quand vous ne le pouvez pas. Un rejet sans temps d'attente invite des retries immédiats, qui transforment une brève limite en tempête de retries.

Appliquer une seule limite globale à tous les partenaires. Le correctif : restreignez la limite par partenaire ou par identifiant, pour qu'un client occupé ne puisse pas affamer les autres. Une limite globale recrée l'injustice exacte que le rate limiting est censé prévenir.

Une seule limite de débit pour chaque partenaire quelle que soit la relation. Le correctif : définissez un petit ensemble de paliers avec des limites qui correspondent à la relation, et donnez aux partenaires un chemin clair pour monter en gamme. Un seul chiffre est trop bas pour vos plus gros partenaires et trop généreux pour les comptes en qui vous n'avez pas encore confiance.

Documenter la limite seulement après que les partenaires se plaignent. Le correctif : publiez les chiffres, les en-têtes, l'attente de backoff et la forme du 429 avant que les partenaires ne construisent. Une limite découverte en l'atteignant est un ticket de support ; une limite lue dans la doc est un intrant de conception.

Resserrer une limite sans préavis. Le correctif : traitez une limite plus stricte comme un changement cassant et donnez un préavis, parce qu'abaisser une limite peut casser une intégration qui marchait très bien hier.

FAQ

Quelle est la différence entre une limite de débit et un quota ? Une limite de débit plafonne la vitesse à laquelle un client peut vous appeler, généralement en requêtes par seconde ou par minute, et protège le service des pics. Un quota plafonne combien un client peut vous appeler sur une fenêtre plus longue, généralement par jour ou par mois, et est souvent lié à un plan. Beaucoup d'API utilisent les deux : une limite de débit par minute pour protéger la stabilité et un quota journalier ou mensuel pour correspondre au palier commercial. Un partenaire a besoin de voir les deux pour dimensionner une intégration, alors documentez-les séparément.

Quel algorithme de rate limiting devrais-je utiliser ? Cela dépend de votre trafic. Une fenêtre fixe est la plus simple mais laisse les pics se doubler aux frontières de fenêtre. Une fenêtre glissante corrige ce problème de frontière avec plus de comptabilité. Un token bucket autorise de courts pics légitimes tout en plafonnant le débit soutenu, ce qui correspond souvent à la façon dont les partenaires appellent réellement une API : calme, puis un pic de travail, puis calme à nouveau. Pour la plupart des API destinées aux partenaires, un token bucket par partenaire est un défaut sensé, mais adaptez le choix à vos vrais profils de trafic.

Quel code de statut une requête sous limite devrait-elle renvoyer ? 429, « Too Many Requests », qui existe exactement pour ce cas. Associez-le à un en-tête Retry-After quand vous pouvez, pour que le client sache combien attendre, et incluez les mêmes en-têtes de limite, restant et reset que vous renvoyez sur les réponses normales. Un 429 avec un signal de retry clair dit au client à la fois ce qui s'est passé et quoi faire, ce que toute bonne réponse d'erreur devrait faire.

Comment les clients devraient-ils répondre à un 429 ? Honorez l'en-tête Retry-After s'il est présent et attendez exactement ce temps avant de réessayer. S'il n'y a pas d'en-tête, utilisez un backoff exponentiel, en doublant l'attente entre les tentatives, avec un petit jitter aléatoire pour que de nombreux clients ne réessaient pas tous au même instant, et arrêtez-vous après un nombre sensé de tentatives plutôt que de réessayer indéfiniment. Si vous livrez un SDK, intégrez cela pour que les partenaires obtiennent le bon comportement par défaut.

Comment fixer les chiffres réels de la limite ? Les bons chiffres dépendent de votre infrastructure, de vos coûts et de votre trafic, donc il n'y a pas de réponse universelle, et vous ne devriez pas copier les figures d'une autre API. Partez de ce que votre service peut soutenir confortablement avec de la marge, fixez des limites de palier qui correspondent aux relations que vous voulez soutenir, et observez l'usage réel. Il est plus facile de relever une limite qui s'est avérée conservatrice que d'abaisser une limite sur laquelle les partenaires ont déjà construit, alors partez sensé et desserrez délibérément.

Quel est le lien entre rate limiting, webhooks et polling ? Le polling est l'une des plus grandes sources de pression sur les limites de débit, parce qu'un client qui vérifie les changements à intervalle serré génère une charge constante, que quelque chose ait changé ou non. Offrir des webhooks laisse les partenaires réagir aux événements au lieu de les sonder, ce qui réduit le volume d'appels qui atteint vos limites. Nous comparons les deux dans webhooks vs polling, et le lien est direct : une bonne livraison d'événements est en partie une stratégie de rate limiting.

Pour aller plus loin

• MDN sur le code de statut 429 pour le sens standard et l'usage prévu de « Too Many Requests ».
• MDN sur l'en-tête Retry-After pour comment dire à un client quand il peut réessayer.
• RFC 6585 qui définit le code de statut 429 dans le standard HTTP.
• RFC 9110 pour la sémantique HTTP plus large dans laquelle s'inscrivent les codes de statut et les en-têtes.
• OWASP pour la perspective sécurité, puisque le rate limiting est aussi un contrôle contre l'abus et le trafic de force brute.

En bref

Le rate limiting est un service rendu à vos partenaires, pas une taxe sur eux, parce qu'il protège chaque client bien élevé de celui qui consommerait sinon toute la capacité. Choisissez une stratégie qui correspond à votre trafic, un token bucket restreint par partenaire est un défaut sensé, puisqu'il tolère les pics légitimes tout en plafonnant la charge soutenue. Rendez la limite visible en renvoyant le plafond, le compte restant et le temps de reset sur chaque réponse, pour qu'un bon client se règle et n'atteigne jamais le mur. Quand un client franchit la ligne, renvoyez un 429 avec un signal de retry clair, et orientez les clients vers un backoff exponentiel avec jitter pour qu'une brève limite ne devienne pas une tempête de retries. Structurez les quotas par palier pour pouvoir accorder l'échelle aux partenaires qui l'ont méritée sans exposer l'API à des comptes en qui vous n'avez pas encore confiance. Et communiquez tout cela, les chiffres, les en-têtes, le backoff et tout changement, avant que les partenaires n'atteignent la limite, parce qu'une limite documentée est une contrainte de conception qu'un partenaire planifie, tandis qu'une limite non documentée est un incident qu'il percute.

Si vous voulez de l'aide pour faire de votre API quelque chose sur quoi les partenaires peuvent construire avec confiance, un Partner Audit examine votre API, votre expérience développeur et votre surface d'intégration, puis vous remet un plan concret de ce qu'il faut améliorer et d'où les partenaires se bloquent.