Ralentir côté client : Retry-After, en-têtes RateLimit et budgets par hôte

Objectif

Respecter les limites d’un serveur sans les deviner, se remettre d’un dépassement sans l’aggraver et éviter que les nombreuses petites requêtes d’un agent provoquent une indisponibilité du service ou un blocage de la clé.

Prérequis

Un client capable d’inspecter les codes de statut et les en-têtes, d’attendre et de conserver un peu d’état par hôte. La connaissance des requêtes idempotentes.

Étapes

1. À la réception de 429 Too Many Requests (RFC 6585) ou de 503 Service Unavailable, rechercher Retry-After. RFC 9110 le définit comme un nombre de secondes ou une date HTTP ; attendre la durée indiquée, puis réessayer une fois. Retry-After est une instruction du serveur qui prime sur toute temporisation locale.
2. En l’absence de Retry-After, appliquer un backoff exponentiel à partir d’un délai de base avec un aléa sur toute la plage, plafonner le délai et limiter le nombre de tentatives. Compter les tentatives par requête, pas par session, et abandonner avec une erreur claire une fois la limite atteinte.
3. Lire les en-têtes indicatifs lorsqu’ils sont présents. Le projet de spécification de l’IETF sur les champs d’en-tête RateLimit définit un champ RateLimit contenant le quota restant et le nombre de secondes avant sa réinitialisation, ainsi qu’un champ RateLimit-Policy décrivant la politique de quota ; un client qui les lit peut ralentir avant le premier 429. Les traiter comme des indications qui peuvent être absentes ou varier dans leur forme d’un serveur à l’autre, et revenir à l’étape 2 à défaut.
4. Maintenir un budget par hôte et par identifiant d’authentification : un nombre maximal de requêtes en cours et un intervalle minimal, ajustés pour réduire le rythme à chaque 429 et ne l’augmenter que lentement. Les agents parallèles qui partagent une clé partagent un budget ; les coordonner au moyen d’un compteur partagé ou d’une file d’attente plutôt que de laisser chacun ralentir indépendamment.
5. Ne jamais retenter aveuglément une écriture non idempotente. Joindre une clé d’idempotence lorsque l’API le permet, afin qu’une nouvelle tentative après expiration du délai ne puisse pas dupliquer l’effet ; sinon, vérifier par une requête si l’effet a eu lieu avant de réessayer.
6. Journaliser chaque 429 avec l’hôte, la catégorie de point de terminaison et l’attente appliquée ; des 429 récurrents sur un point de terminaison signalent un problème de conception (récupérer moins de données, mettre davantage en cache, utiliser un point de terminaison par lots), pas une raison d’augmenter le nombre maximal de tentatives.
7. Privilégier les requêtes conditionnelles et le cache pour les lectures : un 304 Not Modified coûte peu aux deux parties et n’est généralement pas décompté du quota comme une réponse complète, même s’il revient au serveur de préciser cette politique.

Résultat attendu

Les dépassements de limite deviennent rares et se résorbent d’eux-mêmes, les nouvelles tentatives ne dupliquent jamais une écriture, et le service voit un client qui ralentit lorsqu’on le lui demande plutôt qu’un client qui insiste davantage.

Limites et base de vérification

Synthèse de normes et proposition de règles de conduite pour un client ; aucune mesure. Le projet de spécification des en-têtes RateLimit reste un projet : les noms et la sémantique des champs peuvent changer jusqu’à la publication, et de nombreux serveurs envoient à la place leurs propres en-têtes spécifiques au fournisseur.