Surveillez l'utilisation de votre clé avant d'atteindre une limite
Surveiller vos en-têtes de quota au fil de l'eau vous indique quand une limite approche, bien avant qu'une requête ne soit effectivement refusée.
Bien lire les en-têtes X-Quota-Used et X-Quota-Limit
Chaque réponse de l'API, réussie ou non, comporte un ensemble d'en-têtes qui décrivent exactement où vous en êtes par rapport à votre quota. Les lire correctement suppose de comprendre ce que chacun compte.
La paire principale
X-Quota-Limit est la taille de votre quota actuel, soit le quota gratuit quotidien, soit la limite effective d'un forfait Unlimited. X-Quota-Used est le nombre de requêtes déjà décomptées de ce quota au cours de la période en cours. Il est inutile de soustraire l'un de l'autre à la main, puisque X-Quota-Free-Remaining le fait déjà pour vous.
HTTP/1.1 200 OK
X-Quota-Limit: 2500
X-Quota-Used: 1840
X-Quota-Free-Remaining: 660
X-Quota-Network-Used: 1840
X-Credits-Remaining: 0.00
X-Key-IPs-Used: 1
X-Key-IPs-Limit: 3
X-Quota-Reset: 2026-09-22T00:00:00ZUtilisation par clé et utilisation par réseau
X-Quota-Used reflète l'utilisation liée à votre clé, tandis que X-Quota-Network-Used reflète l'utilisation provenant du réseau environnant, car le quota gratuit est partagé entre toutes les adresses IPv4 d'un même /24 et toutes les adresses IPv6 d'un même /48, qu'une clé soit utilisée ou non. Si une clé est appelée depuis plusieurs serveurs situés derrière le même bloc d'adresses, le chiffre du réseau augmentera plus vite que ce que chaque serveur attendrait de son propre trafic.
La paire des emplacements IP
X-Key-IPs-Used et X-Key-IPs-Limit décrivent tout autre chose : le nombre d'adresses sources distinctes qui ont utilisé cette clé récemment, par rapport à la limite glissante de deux ou trois adresses autorisées par clé. Une clé appelée depuis un seul serveur affichera ici une valeur stable de 1. Une clé partagée entre plusieurs serveurs sans lien entre eux, ou copiée dans un script qui finit par s'exécuter sur de nombreuses machines, se rapprochera de la limite. Cela mérite d'être surveillé séparément de votre quota de requêtes, car cela peut bloquer une clé même lorsqu'il reste de nombreuses requêtes gratuites.
Crédit et heure de réinitialisation
X-Credits-Remaining indique votre solde prépayé une fois que vous avez dépassé le quota gratuit et que vous puisez dans le crédit à 0,0001 € par requête. X-Quota-Reset vous indique exactement quand le quota quotidien actuel est réinitialisé, ce qui est plus fiable que de supposer une heure fixe d'après votre propre horloge.
Ce qu'il faut construire à partir de ces en-têtes
Un tableau de bord, une alerte ou simplement une ligne de journal qui lit ces en-têtes après chaque appel vous donne une vue en temps réel de l'utilisation sans appel de rapport séparé, puisque les chiffres arrivent avec la réponse que vous avez déjà obtenue. Les lire ne coûte rien de plus, car ils accompagnent chaque requête que vous envoyiez déjà, que cette requête ait réussi ou renvoyé une erreur.
Une erreur à éviter
Ne lire ces en-têtes que lorsque quelque chose ne va pas signifie que vous découvrez un problème de quota au même moment que vos utilisateurs. Enregistrez au moins X-Quota-Free-Remaining et X-Credits-Remaining à intervalles réguliers, ou après chaque appel dans une intégration à faible trafic, afin qu'une lente progression vers la limite apparaisse comme une tendance dans un tableau de bord plutôt que comme une série soudaine de réponses 429.
Lire les en-têtes de quota sur chaque réponse, plutôt que d'attendre une erreur 429 pour remarquer un problème, fait toute la différence entre un ralentissement maîtrisé et un ralentissement subi. La liste complète des en-têtes est documentée sur la page des limites de débit.