RateLimit et RateLimit-Policy face à X-RateLimit-* : lire les en-têtes de quota qu'envoie une API

Ce que c'est

La RFC 9110 définit un seul en-tête normalisé et déterminant pour cet usage : « the Retry-After field value can be either an HTTP-date or a number of seconds to delay after receiving the response », soit formellement Retry-After = HTTP-date / delay-seconds. La RFC 9110 décrit sa signification sur les réponses 503 et 3xx, et la RFC 6585 permet d'en inclure un dans une réponse 429. Il indique combien de temps le client « ought to wait » (devrait attendre) : c'est la valeur fixée par le serveur lui-même, et non une estimation faite côté client. Par ailleurs, un Internet-Draft actif de l'IETF, draft-ietf-httpapi-ratelimit-headers (révision -11 au moment de la rédaction), propose deux champs informatifs à utiliser avant qu'une requête ne soit limitée : RateLimit-Policy, qui décrit le quota (par exemple RateLimit-Policy: "default";q=100;w=60, soit 100 requêtes par fenêtre de 60 secondes sous une politique nommée « default »), et RateLimit, qui indique le quota actuellement disponible sous cette politique (par exemple RateLimit: "default";r=50;t=30 : 50 unités de quota disponibles, à utiliser dans une fenêtre effective de 30 secondes). Le brouillon avertit que la fenêtre effective « does not imply anything about when the server will increase the available quota » ; t n'est donc pas un horodatage de réinitialisation. Il s'agit toujours d'un brouillon : selon le processus de l'IETF, un Internet-Draft est « valid for a maximum of six months » et ne doit pas être cité comme référence stable ; la syntaxe exacte de ses champs peut donc encore changer avant publication. En pratique, la plupart des API en production sont antérieures à ce brouillon ou l'ignorent, et envoient leurs propres en-têtes, nommés par exemple x-ratelimit-limit, x-ratelimit-remaining et x-ratelimit-reset (l'API REST de GitHub en est un exemple documenté), sous une forme que le brouillon ne régit pas et qui varie selon les fournisseurs.

Pourquoi c'est important

Un client générique qui s'intègre à de nombreuses API rencontrera les trois situations : un en-tête informatif en voie de normalisation, un en-tête propriétaire ad hoc, ou rien d'autre que Retry-After sur le 429 final. Il lui faut donc un ordre de repli qui ne suppose la présence d'aucun d'entre eux.

Comment l'appliquer

• Considérer Retry-After comme faisant autorité dès qu'il est présent, quel que soit le code de statut qui le porte ; analyser les deux formes (nombre entier de secondes et HTTP-date) et attendre au moins ce délai avant de réessayer.
• Si RateLimit et RateLimit-Policy sont présents, les analyser de manière défensive (il s'agit d'un brouillon : les noms de champs, les délimiteurs et même les noms d'en-têtes ont changé d'une révision à l'autre) et s'en servir pour ralentir avant que le quota n'atteigne zéro.
• Si seuls des en-têtes propriétaires de type x-ratelimit-* apparaissent, considérer que leur présence et leur sens sont propres à cette API : ne pas supposer que des noms de champs identiques ont la même signification chez un autre fournisseur.
• Lorsqu'aucun des cas ci-dessus ne se présente, se rabattre sur un backoff exponentiel avec jitter sur 429 et 503, puisque la RFC 9110 n'exige aucun en-tête informatif.

Pièges

Coder en dur un analyseur pour la syntaxe actuelle du brouillon de RateLimit et RateLimit-Policy et le traiter comme un standard achevé ; le brouillon met explicitement en garde contre toute citation « as reference material... other than as work in progress ». Ignorer une valeur Retry-After parce qu'un en-tête informatif laissait penser qu'il restait du quota : Retry-After reflète ce que le serveur a réellement décidé, ce qui peut différer d'une estimation informative envoyée plus tôt.