429 Too Many Requests signifie que le serveur vous applique une limite de débit (rate limiting) : le client a envoyé plus de requêtes sur une période que le serveur ne l’autorise, et il doit attendre avant de réessayer. Rien n’est cassé, et répéter la requête immédiatement ne fait qu’aggraver les choses. Un serveur bien conçu indique combien de temps attendre dans un en-tête Retry-After ; un client bien conçu attend au moins ce délai et, en l’absence d’en-tête, espace ses tentatives avec des délais croissants. Quand un moniteur reçoit une 429, la solution habituelle consiste à l’exempter de la limite ou à vérifier un endpoint qui n’en a pas.
Comment fonctionne la limitation de débit
La RFC 6585 définit le code 429 mais laisse chaque serveur fixer ses règles. Une limite comporte trois éléments :
Qui est compté : une adresse IP, une clé d’API, un compte utilisateur, ou une combinaison. Les limites par IP comptent ensemble tous ceux qui partagent la même adresse.
Ce qui est compté : toutes les requêtes, ou seulement certaines, comme les connexions, les recherches ou un endpoint d’API coûteux, souvent avec une limite plus stricte.
Comment le temps est compté : une fenêtre fixe se réinitialise à chaque minute ; une fenêtre glissante porte sur les 60 dernières secondes ; un token bucket se remplit à un rythme régulier et autorise de courtes rafales dans la limite de sa taille.
La réponse indique souvent où vous en êtes :
HTTP/2 429
retry-after: 30
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: 1793091600
Retry-After est standard et contient soit un nombre de secondes, soit une date HTTP. Les en-têtes X-RateLimit-* relèvent d’une convention répandue plutôt que d’un standard, et leur sens varie : reset peut être un horodatage Unix ou un nombre de secondes, alors lisez la documentation de l’API. Un brouillon de l’IETF définit des champs standard RateLimit et RateLimit-Policy, que certaines API commencent à envoyer.
D’où viennent les erreurs 429
Les API tierces que vous appelez, comme les services de paiement, d’e-mail, de cartographie ou de chat, qui limitent chaque clé ou chaque compte.
Votre propre passerelle d’API ou votre framework, via un middleware de limitation de débit.
Votre serveur web. Le limit_req de nginx répond 503 par défaut ; définissez limit_req_status 429 pour que les clients comprennent qu’ils doivent ralentir au lieu de conclure à une panne.
Les CDN et les WAF, via des règles de limitation de débit. Selon la règle, la réponse est une 429, une 403 ou une page de challenge.
La protection des connexions et des formulaires d’un CMS ou d’un plugin de sécurité, qui limite le nombre de tentatives par adresse.
Gérer une 429 côté client
Respectez Retry-After. Attendez au moins le délai indiqué. Réessayer plus tôt vous vaut généralement une nouvelle 429 et peut prolonger un blocage.
Utilisez un backoff exponentiel avec jitter. Sans Retry-After, attendez plus longtemps après chaque échec, par exemple 1, 2, 4 puis 8 secondes, plus une part aléatoire, pour que de nombreux clients ne réessaient pas tous au même moment.
Plafonnez les nouvelles tentatives. Après quelques essais, abandonnez et signalez l’erreur, ou placez le travail dans une file d’attente pour plus tard.
Envoyez moins de requêtes. Mettez les réponses en cache, utilisez les endpoints de traitement par lots, demandez des pages plus grandes, et utilisez les webhooks plutôt que le polling quand l’API en propose.
Étalez les tâches planifiées. Des cron jobs qui démarrent tous à l’heure pile atteignent les limites ensemble ; décalez-les de quelques minutes. Le guide des expressions cron explique comment faire.
async function fetchWithBackoff(url, options = {}, attempts = 5) {
for (let attempt = 0; attempt < attempts; attempt++) {
const response = await fetch(url, options);
if (response.status !== 429) return response;
const retryAfter = Number(response.headers.get(‘retry-after’));
const wait = retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 1000 + Math.random() * 1000;
await new Promise((resolve) => setTimeout(resolve, wait));
}
throw new Error(‘Still rate limited after ‘ + attempts + ‘ attempts’);
}
Cette ébauche ne lit Retry-After qu’en secondes ; un code de production doit aussi accepter la forme date.
Définir des limites de débit sur votre propre site
Répondez 429, pas 503 ni 403. Une 503 ressemble à une panne et une 403 à un refus définitif ; une 429 indique précisément aux clients et aux outils de surveillance ce qui s’est passé.
Envoyez Retry-After, pour que les clients n’aient pas à deviner.
Limitez par clé ou par compte quand c’est possible. Les limites par IP pénalisent les bureaux, les écoles et les réseaux mobiles, où de nombreuses personnes partagent la même adresse.
Autorisez les rafales. Le chargement d’une page peut déclencher des dizaines de requêtes d’un coup ; un token bucket qui laisse de la place pour une rafale évite de bloquer les visiteurs normaux.
Exemptez votre surveillance, ou donnez-lui son propre endpoint de health check sans limite.
# nginx: 10 requests a second per address, bursts of 20, answered with 429
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
limit_req_status 429;
}
}
Pourquoi un outil de surveillance de disponibilité peut recevoir une 429
Une vérification par minute semble anodine, mais les requêtes s’additionnent de façons faciles à négliger :
Plusieurs moniteurs sur un même hôte. Dix moniteurs sur la même API, vérifiant chacun toutes les minutes, font dix requêtes par minute depuis le même client, plus les revérifications de confirmation en cas d’échec.
Des limites strictes sur le chemin vérifié. Les pages de connexion, la recherche et les endpoints de formulaires n’autorisent souvent que quelques requêtes par minute et par adresse.
Des adresses partagées. Les vérifications d’un service de surveillance partent de quelques adresses connues. Une limite par IP compte ensemble toutes les vérifications venant de cette adresse, y compris celles d’autres utilisateurs sur le même site ou la même API publics.
Une règle anti-bots qui limite le débit. Certains pare-feu comptent séparément les clients automatisés et les limitent plus sévèrement que les navigateurs.
Que faire, dans l’ordre : exempter le moniteur de la limite par ses adresses IP, surveiller un endpoint de santé sans limite, vérifier moins souvent, ou regrouper les moniteurs qui interrogent la même API. N’acceptez pas la 429 comme « disponible » partout, car une limite qui commence à bloquer vos vrais utilisateurs mérite d’être connue. Les codes de statut HTTP en surveillance explique quels codes traiter comme des échecs, et la checklist de surveillance d’API ce qu’il faut surveiller d’autre sur une API.
Les erreurs 429 et Uptimecheck
Dans la surveillance de disponibilité et la surveillance d’API d’Uptimecheck, une 429 se situe hors des statuts attendus par défaut (200 à 399) : elle compte donc comme une panne dès qu’une seconde vérification la confirme. Quand le serveur répond par une simple 429, l’incident indique que nos vérifications sont soumises à une limite de débit, cite la valeur de Retry-After si le serveur en a envoyé une, et suggère d’exempter les requêtes dont le user agent contient « Uptimecheck », de vérifier moins souvent ou d’utiliser un endpoint sans limite. Les vérifications partent de Stockholm, en Suède ; comment autoriser Uptimecheck à travers un pare-feu liste les adresses à exempter, avec des règles pour Cloudflare, y compris ses règles de limitation de débit, et pour nginx. Vous choisissez l’intervalle de chaque moniteur, de toutes les minutes à toutes les heures.
Uptimecheck applique les mêmes règles lorsqu’il envoie vos alertes. Si Slack, Microsoft Teams, Discord ou PagerDuty répond 429, l’alerte est renvoyée après 30 secondes, 2 minutes, 10 minutes puis 30 minutes, et jamais plus tôt que ce que demande le Retry-After du service, dans la limite d’une heure. Consultez pourquoi les alertes peuvent ne pas arriver pour savoir ce qui se passe quand un canal continue d’échouer.
Distinguez une limite de débit d’une panne. Essayez Uptimecheck gratuitement pendant 14 jours, sans carte bancaire.