Une limite de consommation protège une API contre les pics de trafic, les erreurs d’intégration et les usages susceptibles de dégrader le service. Elle influe aussi sur l’expérience des personnes qui en dépendent : une règle trop stricte peut interrompre des processus légitimes, tandis qu’une règle trop permissive laisse peu de marge de réaction en cas de surcharge.
Il ne s’agit pas de choisir un nombre universel de requêtes par minute, mais de déterminer quelle ressource protéger, quels sont les comportements habituels et comment rendre la limite compréhensible et prévisible. Ce guide présente des critères pour définir des quotas, gérer les dépassements et réviser les règles à partir de données concrètes.
Les problèmes que les limites résolvent et ceux qu’elles ne remplacent pas
Les limites contrôlent le volume qu’un client ou un processus peut consommer pendant une période donnée, ou le nombre d’opérations simultanées qu’il peut maintenir. Elles aident à répartir la capacité, à contenir les pics et à réduire l’impact d’erreurs, comme une boucle qui répète les appels sans pause. Elles peuvent également soutenir une offre commerciale assortie de niveaux d’utilisation définis.
Toutefois, un quota ne remplace ni la planification de capacité, ni la protection contre les attaques, ni la conception efficace de l’API. Une limite peut réduire la pression, mais elle ne corrige ni une requête coûteuse, ni une dépendance lente, ni une stratégie de nouvelles tentatives défaillante. À elle seule, elle ne garantit pas non plus une répartition équitable des ressources entre les consommateurs.
Avant de définir une limite, précisez son objectif : s’agit-il de protéger une opération coûteuse, de réserver de la capacité à différents clients ou d’établir une condition de service ? Si plusieurs objectifs sont en jeu, distinguez-les. Les règles techniques de protection et les conditions commerciales peuvent coïncider, mais ne doivent pas être confondues : leurs critères d’évolution et leurs besoins de communication diffèrent.
Identifiez les consommateurs et les opérations avant de fixer des seuils
Un quota n’est utile que si le système peut attribuer les requêtes à une identité stable. Déterminez si le consommateur correspond à un compte, une application enregistrée, un identifiant d’accès, une équipe interne ou un utilisateur final. Une adresse IP peut fournir un indice supplémentaire, mais elle ne désigne pas toujours un client : plusieurs personnes peuvent partager la même adresse et un client peut en changer.
Classez ensuite les opérations. Lire une ressource mise en cache n’a généralement pas le même coût que générer un rapport, lancer une exportation ou effectuer une recherche étendue. Regrouper tous les points de terminaison sous une limite unique simplifie les explications, mais peut traiter de façon inégale des appels dont le coût varie fortement.
Analysez le trafic réel et les scénarios prévus avant de fixer les valeurs. Examinez les tendances par consommateur, point de terminaison, heure, durée des requêtes, niveau de concurrence et erreurs. Vérifiez aussi quelles intégrations traitent des lots ou effectuent des synchronisations périodiques. Une intégration légitime peut concentrer ses appels sur une courte période sans générer un trafic soutenu.
- Par compte ou application : facilite l’application d’une règle stable pour le client, à condition que son identité soit correctement associée.
- Par opération : permet de protéger des fonctionnalités dont les coûts ou les capacités diffèrent.
- Par ressource partagée : aide à limiter la pression sur une base de données, un fournisseur ou un processus commun.
La portée choisie doit correspondre à la ressource protégée. Si la limite par identifiant d’accès peut être contournée en en créant de nouveaux, le compte est peut-être l’unité appropriée. Si une opération partage une ressource avec d’autres points de terminaison, un quota individuel peut ne pas suffire à la protéger.
Quotas, concurrence et pics : choisissez le contrôle adapté
Un quota limite le volume de requêtes sur une période donnée. Il permet d’exprimer un budget de consommation et se communique facilement, mais la période et la définition d’une requête doivent être claires. Une fenêtre fixe peut permettre de concentrer le trafic au moment du changement de période ; une fenêtre glissante ou un système fondé sur des jetons peut atténuer cet effet, au prix d’une mise en œuvre et d’explications plus complexes.
Une limite de concurrence restreint le nombre d’opérations pouvant être actives simultanément. Elle est utile lorsque les requêtes sont longues ou consomment des ressources pendant leur exécution. Elle ne limite pas nécessairement le volume total : un client peut terminer de nombreuses opérations courtes les unes après les autres. Elle peut donc être associée à un quota lorsque les deux risques sont pertinents.
Le contrôle des pics permet d’absorber une hausse brève sans accepter indéfiniment un rythme élevé. Il convient aux synchronisations ou au lancement de processus, à condition que le service puisse gérer ce pic. Il ne faut pas autoriser ces pointes au seul motif que le trafic moyen semble faible : la capacité disponible au moment du pic compte également.
Pour choisir, demandez-vous ce qui se dégrade en premier : le budget de travail cumulé, le nombre d’opérations simultanées ou la capacité instantanée. Utilisez le contrôle le plus simple qui protège le risque constaté. Combiner des mécanismes sans raison claire peut rendre les limites difficiles à diagnostiquer et produire des messages contradictoires.
Gérez les dépassements de manière prévisible
Lorsqu’un consommateur dépasse une limite temporaire, la réponse de rejet doit être distinguée d’une défaillance imprévue du service. Dans de nombreux cas, le code HTTP 429 indique qu’un trop grand nombre de requêtes a été reçu sur une période donnée. Si le système peut estimer à quel moment une nouvelle requête sera acceptée, il peut l’indiquer au moyen de l’en-tête Retry-After. La réponse devrait également préciser quelle limite a été atteinte et où consulter les règles applicables.
Ne promettez pas un délai de rétablissement que le système ne peut garantir. S’il est impossible d’indiquer quand la capacité sera de nouveau disponible, évitez de suggérer des tentatives immédiates. Les clients doivent appliquer un délai d’attente progressif, limiter le nombre de tentatives et, le cas échéant, ajouter une variation aléatoire au délai afin d’éviter que toutes les nouvelles tentatives surviennent en même temps.
Si la requête déclenche une opération coûteuse ou non idempotente, indiquez comment gérer son rejet et s’il est sans risque de la renvoyer. Un client ne doit pas interpréter chaque erreur comme une autorisation à répéter une opération sans limite. Documentez également les différences entre un quota épuisé, un identifiant d’accès invalide et une indisponibilité temporaire.
Concevez des exceptions transparentes et révisables
Certains motifs légitimes peuvent justifier un ajustement de quota : une migration, une synchronisation convenue ou une évolution démontrée des habitudes d’utilisation. Définissez qui peut demander une exception, quelles informations sont requises, qui l’approuve et à quel moment elle sera réexaminée. Consignez sa portée, sa durée et la personne responsable afin qu’elle ne devienne pas permanente par inertie.
Évitez les exceptions informelles liées à une personne précise ou à des accords inconnus de l’équipe opérationnelle. Si le changement répond à une condition commerciale, coordonnez la communication entre les équipes produit, commerciale et technique. S’il répond à un besoin technique temporaire, indiquez clairement les critères qui permettront d’y mettre fin.
Les quotas peuvent évoluer, mais le processus ne devrait pas prendre au dépourvu les intégrations actives. Communiquez à l’avance les changements importants, précisez qui est concerné et proposez une voie de migration lorsque c’est possible. Publiez les limites actuelles et indiquez s’il s’agit de valeurs garanties ou de seuils susceptibles d’être révisés. La transparence sur les changements fait partie des règles, ce n’est pas un simple détail administratif.
Suivez les métriques sans encourager les nouvelles tentatives abusives
Observez à la fois la consommation acceptée et les requêtes rejetées. Ventilez les données par consommateur et par opération, puis mettez-les en relation avec la latence, les erreurs, la concurrence et la pression sur les dépendances. Une hausse des réponses 429 peut signaler un abus, mais aussi un quota mal calibré, une évolution du produit ou une intégration qui n’a pas reçu l’information nécessaire.
Interprétez les signaux conjointement. Si un client atteint occasionnellement la limite pendant une tâche prévue et que la capacité reste disponible, les règles concernant les pics ou la durée de la période ne correspondent peut-être pas à ses habitudes. Si plusieurs consommateurs font simultanément augmenter la latence et la saturation d’une dépendance, relever leurs quotas risque d’aggraver la situation.
Comptabilisez et analysez les nouvelles tentatives : de nombreux appels rejetés peuvent gonfler le trafic et masquer la demande réelle de travail. Repérez les séquences répétées sans délai d’attente, les concentrations juste après la réinitialisation d’une fenêtre et les appels échoués qui se répètent sans changement. Lorsque c’est possible, partagez ces observations avec le consommateur et mesurez l’effet de chaque ajustement avant de l’étendre à tous.
Liste de vérification avant de publier une politique
- Définissez la ressource ou le risque protégé par chaque limite.
- Identifiez le consommateur au moyen d’une clé stable et expliquez comment ses identifiants d’accès sont regroupés.
- Distinguez les opérations lorsque leur coût ou leur mode d’utilisation diffère.
- Précisez l’unité, la période, la portée, la concurrence et le comportement en cas de pic.
- Documentez la réponse en cas de dépassement et les consignes relatives aux nouvelles tentatives.
- Établissez une procédure vérifiable pour les exceptions et les changements.
- Surveillez les rejets, les nouvelles tentatives, la latence et la pression sur les ressources.
- Réexaminez les règles à partir des données et, lorsque c’est possible, annoncez les changements avant leur application.
La meilleure politique n’est pas celle qui autorise le plus grand nombre d’appels, mais celle qui protège le service sans rendre son utilisation imprévisible pour les clients et les équipes internes. Commencez par définir le risque concret, appliquez des limites compréhensibles et ne les ajustez que lorsque les métriques et les habitudes d’intégration justifient cette décision.