Limitation du débit de l'API : 4 algorithmes que tout développeur devrait connaître
Fenêtre fixe, fenêtre coulissante, compartiment de jetons et compartiment qui fuit expliqués avec des diagrammes, des en-têtes X-RateLimit et la logique de nouvelle tentative Node.js que vous pouvez copier-coller.
Votre travail par lots déclenche 200 requêtes en 3 secondes et chaque réponse revient 429 Too Many Requests.
Votre processeur webhook martèle une API tierce et est bloqué pendant 15 minutes. L'intégration d'un client
devient silencieux car leur boucle de nouvelle tentative brûle le quota quotidien au cours de la première heure. Ces échecs partagent
une cause fondamentale : le code ne respecte pas les limites de débit.
Ce guide couvre les quatre principaux algorithmes de limitation de débit et vous montre comment lire X-RateLimit
en-têtes de n'importe quelle API et vous donne un copier-coller du code Node.js pour une logique de nouvelle tentative avec un intervalle exponentiel.
Les quatre algorithmes de limitation de débit
Chaque limiteur de débit répond à la même question : « cette demande doit-elle être acceptée ou dois-je la rejeter ? Les quatre algorithmes diffèrent dans la manière dont ils suivent le temps et gèrent les rafales.
1. Fenêtre fixe
L'approche la plus simple. Divisez le temps en intervalles fixes (par exemple, 1 minute). Comptez les demandes par intervalle. Lorsque le décompte atteint la limite, rejetez tout jusqu'au début de l'intervalle suivant.
La fenêtre fixe est facile à construire : un compteur et un horodatage par client. L'inconvénient est le problème de frontière. Un client peut envoyer la limite complète à la fin d'une fenêtre et la limite complète au début du suivant, obtenez 2x le taux prévu en une courte rafale. L'ancienne API de GitHub le limiteur de débit utilisait des fenêtres fixes ; depuis, ils ont adopté des approches plus sophistiquées.
2. Fenêtre coulissante
Au lieu de se réinitialiser à des limites fixes, la fenêtre glisse à chaque demande. A un moment donné, le limiteur revient sur les N dernières secondes et compte les requêtes dans cette période.
La fenêtre coulissante élimine le problème d'éclatement des limites. Le coût est plus élevé en mémoire : vous stockez un horodatage
pour chaque demande, pas un seul compteur. Rédis ZRANGEBYSCORE rend cela pratique à grande échelle.
Cloudflare et de nombreuses passerelles API utilisent des fenêtres glissantes pour les limites de débit par utilisateur.
3. Seau de jetons
Imaginez un seau contenant des jetons. Chaque demande coûte un jeton. Les jetons se rechargent à un tarif fixe. Si le compartiment est vide, la demande est rejetée. Si le seau est plein, les jetons excédentaires ne s'accumulent pas.
Le compartiment à jetons est l'algorithme le plus populaire en production. Stripe, AWS API Gateway et la plupart des services cloud les fournisseurs en utilisent des variantes. La capacité du seau contrôle la taille de la rafale et le taux de remplissage contrôle débit soutenu. Deux paramètres vous offrent un contrôle précis sur la forme du trafic.
4. Seau qui fuit
L’inverse du seau de jetons. Les demandes remplissent un seau. Le seau se vide à un rythme constant. Si le le bucket déborde, les demandes excédentaires sont rejetées. Le taux de sortie reste constant quelle que soit l'entrée éclate.
Le bucket qui fuit fonctionne bien pour façonner le trafic là où vous avez besoin d'un taux de sortie constant : les travailleurs de file d'attente, livraison de webhooks et pipelines d'encodage vidéo. Le compromis est que les rafales sont plutôt mises en file d'attente que servi; la latence augmente sous charge.
Comparaison des quatre algorithmes
| Algorithme | L'éclatement est autorisé ? | Mémoire | Cas d'utilisation courant |
|---|---|---|---|
| Fenêtre fixe | Salves de bord (2x à la limite) | Faible (1 compteur) | Compteurs simples, analyses |
| Fenêtre coulissante | Lisse, sans pointes de limite | Moyen (horodatage par demande) | Limites de l'API par utilisateur |
| Seau de jetons | Des rafales contrôlées jusqu'à la capacité | Faible (2 valeurs) | La plupart des API de production (Stripe, AWS) |
| Seau qui fuit | Taux de sortie constant en file d'attente | Moyen (file d'attente) | Organisation du trafic, agents de file d'attente |
Lecture des en-têtes X-RateLimit
La plupart des API incluent des informations sur la limite de débit dans les en-têtes de réponse. Trois en-têtes vous disent tout vous devez rester sous la limite :
X-RateLimit-Limit: nombre maximum de requêtes autorisées par fenêtreX-RateLimit-Remaining: requêtes que vous avez laissées dans la fenêtre actuelleX-RateLimit-Reset: Horodatage Unix (secondes) lorsque la fenêtre se réinitialise
Lorsque vous dépassez la limite, l'état de la réponse est 429 Too Many Requests et le
Retry-After l'en-tête vous indique combien de secondes attendre.
Essayez-le avec l'API de Botoi. Cette commande curl hache une chaîne et imprime les en-têtes de limite de débit :
En-têtes de réponse :
Cela vous indique que la limite est de 5 requêtes par fenêtre, qu'il vous en reste 4 après cette requête, et que le la fenêtre se réinitialise à l'horodatage Unix donné. Suivez ces valeurs dans votre client HTTP pour éviter de heurter 429 en premier lieu.
Conseil: Convertir X-RateLimit-Reset à un temps d'attente :
waitMs = (resetTimestamp - Math.floor(Date.now() / 1000)) * 1000
Réessayez la logique avec une interruption exponentielle dans Node.js
Lorsqu'un 429 arrive, ne réessayez pas immédiatement. Une boucle de nouvelle tentative serrée aggrave le problème : vous restez votre débit est limité plus longtemps et le serveur vous marque comme abusif. Utilisez plutôt un intervalle exponentiel avec gigue.
Utilisez-le avec n'importe quel point de terminaison :
La fonction recherche un Retry-After en-tête en premier. Si le serveur vous indique combien de temps
attendre, respectez-le. Si aucun en-tête n'existe, il revient à une attente exponentielle : 1 seconde, 2 secondes,
4 secondes, 8 secondes. La gigue aléatoire (0-500 ms) évite le problème du troupeau tonitruant où des centaines de
les clients réessayent exactement au même moment.
Limitation proactive : évitez les 429 avant qu'ils ne se produisent
La nouvelle tentative réactive gère les échecs après qu'ils se produisent. La limitation proactive les empêche. Si tu sais la limite de débit (à partir de documents ou d'en-têtes), rythmez vos requêtes côté client.
Ce limiteur de débit côté client suit les horodatages des demandes dans une fenêtre glissante. Avant chaque demande, il vérifie si la fenêtre est pleine et attend si nécessaire. Vous envoyez des demandes au maximum de sécurité taux sans un seul 429.
Le modèle de limitation de débit de Botoi
Botoi utilise un système de limitation de débit à deux niveaux :
| Plan | Rafale (par minute) | Quota | Authentification |
|---|---|---|---|
| Gratuit (0$) | 5 requêtes/min | 100/jour | Aucun (basé sur IP) |
| Entrée (9 $/mois) | 30 req/min | 300 000/mois | Clé API |
| Pro (49 $/mois) | 300 req/min | 3 000 000/mois | Clé API |
| Entreprise (199 $/mois) | 1 000 requêtes/min | 30 000 000/mois | Clé API |
L'accès anonyme suit les demandes par adresse IP. Le décompte quotidien se réinitialise à minuit UTC via un Compteur Cloudflare KV. Les requêtes authentifiées utilisent la clé API pour l'identification et les limites sont appliqués par Unkey limiteur de débit de seau de jetons en bordure.
Chaque réponse de api.botoi.com comprend les trois X-RateLimit en-têtes
décrit ci-dessus, afin que votre logique de nouvelle tentative fonctionne de la même manière quel que soit le plan.
Approches éprouvées pour les consommateurs d'API
- Lisez les en-têtes de chaque réponse. Ne codez pas en dur les limites de débit à partir de la documentation. Les API modifient les limites sans préavis. Les en-têtes sont la source de la vérité.
- Utilisez un recul exponentiel avec gigue. Les intervalles de nouvelle tentative fixes provoquent une synchronisation tentatives entre les clients. La gigue répartit la charge.
- Lot où l'API le prend en charge. Une demande avec 10 articles coûte 1 limite de tarif jeton. Dix demandes individuelles coûtent 10.
- Mettre en cache les réponses. Si les données ne changent pas entre les requêtes, stockez le résultat et ignorez l'appel API. Les enregistrements DNS, les certificats SSL et les données WHOIS changent rarement en quelques minutes.
- Utilisez une file d'attente pour le travail en arrière-plan. Ne lancez pas d'appels d'API à partir d'une boucle chaude. Pousser travaillez sur une file d'attente (BullMQ, SQS, Cloudflare Queues) et traitez les éléments à un rythme contrôlé.
-
Surveillez votre quota restant. Enregistrer
X-RateLimit-Remainingà votre tableau de bord des métriques. Définissez une alerte lorsqu'elle descend en dessous de 20 % de la limite.
Points clés
- Quatre algorithmes dominent. La fenêtre fixe est la plus simple. Le compartiment à jetons est le plus populaire. La fenêtre coulissante élimine les rafales de limites. Le seau qui fuit lisse la production.
-
Les en-têtes X-RateLimit sont votre API. Lire
Limit,Remaining, etResetà chaque réponse pour rester sous le plafond. -
Recul exponentiel avec gestion de la gigue 429 s. Copiez le
fetchWithRetryfonction ci-dessus dans votre base de code et encapsulez chaque appel d'API externe. - La limitation proactive empêche les 429. Rythmez vos demandes côté client au lieu d'attendre que le serveur repousse.
- Aucun compte requis pour tester. Accédez à n'importe quel point de terminaison botoi à api.botoi.com avec 5 requêtes gratuites par minute pour voir les en-têtes de limite de débit en action.
FAQ
- Qu'est-ce que la limitation de débit des API et pourquoi les API l'utilisent-elles ?
- La limitation du débit limite le nombre de demandes qu'un client peut effectuer dans une fenêtre de temps. Les API l'utilisent pour protéger les serveurs contre la surcharge, prévenir les abus, garantir un partage équitable des ressources entre les clients et maintenir les coûts d'infrastructure prévisibles. Sans cela, un seul client pourrait affamer tous les autres.
- Que signifient les en-têtes X-RateLimit ?
- X-RateLimit-Limit correspond au nombre maximal de requêtes autorisées par fenêtre. X-RateLimit-Remaining est le nombre qu'il vous reste. X-RateLimit-Reset est un horodatage Unix lorsque la fenêtre est réinitialisée. Retry-After (sur 429 réponses) vous indique combien de secondes attendre avant de réessayer.
- Comment dois-je gérer une réponse 429 Too Many Requests ?
- Lisez l’en-tête Retry-After et attendez autant de secondes. Si aucun en-tête Retry-After n'existe, utilisez un intervalle exponentiel : attendez 1 seconde après les premiers 429, 2 secondes après le deuxième, 4 secondes après le troisième, et ainsi de suite. Ajoutez une gigue aléatoire (0 à 500 ms) pour éviter les problèmes de troupeau lorsque de nombreux clients réessayent en même temps.
- Quel algorithme de limitation de débit est le plus courant ?
- Le bucket de jetons est le plus courant dans les API de production. Stripe, AWS et la plupart des fournisseurs de cloud en utilisent des variantes. Le compartiment de jetons permet des rafales contrôlées tout en appliquant un débit soutenu, qui correspond mieux aux modèles de trafic réels que les fenêtres fixes.
- Le taux botoi limite-t-il les demandes anonymes ?
- Oui. Les requêtes anonymes (pas de clé API) reçoivent 5 requêtes par minute en rafale et 100 requêtes par jour, suivies par adresse IP. Les requêtes authentifiées sur les forfaits payants bénéficient de limites plus élevées : Starter autorise 30/min, Pro autorise 300/min et Business autorise 1 000/min.
Commencez a construire avec botoi
150+ endpoints API pour la recherche, le traitement de texte, la generation d'images et les utilitaires pour developpeurs. Offre gratuite, sans carte bancaire.