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.
Gérer une réponse 429 sans perdre la requête
Un code de statut 429 n'est pas le même type d'échec qu'un 400 ou un 404. Il signifie que la requête était bien formée et aurait fonctionné, mais que votre quota pour la période en cours est épuisé.
À quoi ressemble la réponse
HTTP/1.1 429 Too Many Requests
X-Quota-Limit: 2500
X-Quota-Used: 2500
X-Quota-Free-Remaining: 0
X-Credits-Remaining: 0.00
X-Quota-Reset: 2026-09-22T00:00:00Z
{
"status": "error",
"error": {"code": "quota_exceeded", "message": "Daily quota exceeded"}
}Ne jetez pas la requête
L'erreur la plus courante consiste à traiter un 429 comme un 400, en l'enregistrant comme un échec avant de passer à autre chose. La recherche que voulait l'utilisateur ou votre script reste parfaitement valide, elle doit simplement s'exécuter plus tard ou avec d'autres identifiants. Placez la charge utile de la requête d'origine dans une file de nouvelles tentatives au lieu de la jeter.
Lire l'heure de réinitialisation
L'en-tête X-Quota-Reset de la réponse 429 vous indique exactement quand le quota quotidien est réinitialisé. Une tâche en arrière-plan peut attendre jusqu'à ce moment puis reprendre la file, plutôt que d'interroger l'API en boucle ou de deviner un intervalle fixe entre les tentatives.
Un second scénario à prévoir
Un 429 ne signifie pas toujours que le quota de toute la journée est épuisé. Si X-Key-IPs-Used a atteint X-Key-IPs-Limit, une clé peut être temporairement refusée depuis une nouvelle adresse source alors que les requêtes depuis ses adresses habituelles réussiraient encore. Identifier l'en-tête qui explique réellement le 429, épuisement du quota ou limite d'emplacements IP, change la solution : attendre une réinitialisation dans un cas, réduire le nombre de machines distinctes utilisant la même clé dans l'autre.
Deux façons de dépasser la limite dès maintenant
Si attendre n'est pas acceptable, deux options immédiates s'offrent à vous : recharger du crédit prépayé à 0,0001 € par requête, ou passer à une clé Unlimited à 50 € par mois s'il s'agit d'une situation récurrente plutôt que d'un pic ponctuel. Les deux suppriment le plafond quotidien qui a déclenché le 429 au départ.
Distinguer les limites de clé des limites de réseau
Comme le quota gratuit est partagé sur tout un /24 en IPv4 ou un /48 en IPv6, un 429 peut survenir à cause du trafic d'autres adresses du même réseau, et pas seulement de l'utilisation de votre propre clé. Consultez X-Quota-Network-Used en plus de X-Quota-Used pour distinguer les deux situations avant de décider si une mise à niveau de clé réglera vraiment quelque chose.
Une erreur à éviter
Relancer immédiatement une requête échouée, en boucle serrée, dès qu'un 429 revient ne fait qu'ajouter des appels échoués sur un quota déjà épuisé, sans vous rapprocher d'une requête qui fonctionne. Attendez l'heure de réinitialisation indiquée par l'en-tête, ou un délai fixe raisonnable si le code ne lit pas les en-têtes, plutôt que de solliciter à nouveau l'endpoint sans attendre.
Traiter un 429 comme « réessayez bientôt » plutôt que comme « cela a échoué » permet à une file d'attente de traverser sans heurt une réinitialisation de quota au lieu de perdre du travail. Les formats d'erreur de l'API sont détaillés sur la page des erreurs, et les options de quota actuelles sur la page des tarifs.