Qu’est-ce que la limitation du débit des API ?

La limitation du débit des API restreint les requêtes qu’un client peut effectuer sur une période définie ou dans les limites d’un budget de ressources. Un service peut appliquer des limites par compte, informations d’identification, point de terminaison, adresse ou autre périmètre d’utilisation.

Un limiteur de débit comptabilise les requêtes, ou un coût pondéré par requête, par rapport à un quota associé à une partition telle qu’un compte, un ensemble d’informations d’identification, une adresse IP ou un point de terminaison, et plusieurs politiques peuvent s’appliquer à la même requête. L’algorithme de comptage détermine le traitement des rafales. Un compteur à fenêtre fixe se réinitialise à chaque limite de fenêtre ; un client peut donc consommer le quota d’une fenêtre juste avant la réinitialisation, puis celui de la fenêtre suivante juste après. Une fenêtre glissante atténue cet effet, par exemple en ajoutant le compte de la fenêtre précédente pondéré par la proportion de cette fenêtre qui chevauche encore la période courante. Un seau à jetons ajoute des jetons à débit constant jusqu’à une capacité fixe, et cette capacité limite la rafale qu’il admet. Un seau percé se vide à débit constant ; l’implémentation de NGINX retarde les requêtes excédentaires par défaut et les rejette lorsqu’elles dépassent la taille de rafale configurée. Un service peut faire fonctionner plusieurs limiteurs en parallèle, par exemple un débit de requêtes, un plafond de requêtes simultanées et un budget distinct pour les opérations coûteuses ou créatrices de contenu ; respecter une limite ne signifie donc pas les respecter toutes. Lorsqu’une requête est refusée, la réponse peut indiquer combien de temps attendre, ce qui permet aux clients d’étaler leurs nouvelles tentatives au lieu de revenir tous en même temps.

HTTP définit le statut 429 Too Many Requests pour une requête soumise à une limitation de débit, et la réponse peut inclure un en-tête Retry-After, mais aucun des deux n’est garanti. GitHub indique dans sa documentation pouvoir répondre avec 403 ou 429, accompagné d’un en-tête x-ratelimit-remaining valant 0 ou d’un message d’erreur indiquant qu’une limite de débit a été dépassée, et le module limit_req de NGINX rejette les requêtes avec 503, sauf si limit_req_status est défini. Détectez la limitation à partir des codes de statut, des en-têtes et du corps d’erreur documentés par l’API, pas uniquement à partir de 429.
Retry-After est soit un nombre de secondes à attendre après réception de la réponse, soit une date HTTP ; un client doit donc analyser les deux formes. Certaines API indiquent l’attente ailleurs : GitHub utilise aussi x-ratelimit-reset, un instant exprimé en secondes depuis l’époque Unix en UTC, et d’autres services placent un délai dans le corps d’erreur JSON. Lisez le délai à l’endroit et dans l’unité documentés par l’API.
Aucune norme finalisée n’existe pour annoncer le quota restant. Les champs d’en-tête RateLimit et RateLimit-Policy font l’objet d’un Internet-Draft de l’IETF (révision 11, datée de mai 2026), pas d’une RFC, et les API déployées utilisent des noms propres aux fournisseurs, tels que x-ratelimit-remaining. Le projet demande aux clients de ne pas considérer le quota annoncé comme une garantie et donne la priorité à Retry-After lorsqu’une réponse contient les deux.
Le quota indiqué peut être inexact, car les limiteurs répartis sur de nombreux serveurs partagent leurs compteurs ou en utilisent des approximations. GitHub précise que le compte restant peut varier d’une réponse à l’autre lorsque les requêtes sont traitées dans plusieurs régions et déconseille toute logique dépendant d’un compte restant exact ; Amazon API Gateway décrit ses limitations et quotas comme des objectifs appliqués au mieux, pas comme des plafonds garantis. Cadencez les requêtes à partir des valeurs indiquées, mais continuez à gérer les réponses de limitation même lorsque la dernière réponse indiquait un quota disponible.

Les limites de débit influencent la conception de tout client qui envoie des requêtes en masse ou en parallèle, notamment pour les importations, les boucles d’interrogation, les traitements par lots et la logique de nouvelles tentatives. Repérez les limites documentées de l’API et sa réponse de limitation avant de construire le client, puis attendez au moins aussi longtemps que cette réponse l’indique, ajoutez une variation aléatoire pour que les workers parallèles ne réessaient pas tous au même instant et plafonnez le nombre de tentatives. Lorsqu’une réponse de limitation n’indique aucun délai, utilisez la solution de repli documentée par l’API ou, à défaut, un délai qui augmente de façon exponentielle à chaque tentative jusqu’à un maximum. Réessayer immédiatement ajoute de la charge et peut prolonger la limitation, et certains fournisseurs, dont GitHub, avertissent qu’une intégration continuant à envoyer des requêtes pendant une limitation peut être bannie.

Transloadit limite le débit de sa propre API et documente les limites actuelles sur sa page consacrée à la limitation de débit. Une requête rejetée pour dépassement d’une limite de création ou de simultanéité renvoie une erreur JSON indiquant un délai d’attente recommandé en secondes, et les SDK officiels de Transloadit appliquent déjà ce délai avant de réessayer.

L’attente indiquée est un délai recommandé avant une nouvelle tentative : la documentation précise qu’elle ne garantit pas qu’une capacité sera disponible à son terme. La même page décrit une limite distincte pour les requêtes à haute fréquence, et la réponse présentée pour cette limite ne contient aucun délai d’attente ; un client qui la gère doit donc définir son propre délai avant de réessayer.

Explorer les fonctionnalités de la plateforme Transloadit

Qu’est-ce que la limitation du débit des API ?

Fonctionnement de la limitation du débit des API

Points clés

Quand la limitation du débit des API est importante

Comment Transloadit vous aide avec la limitation du débit des API

Références

Transformer vos connaissances sur les médias en une chaîne de traitement opérationnelle