429 Too Many Requests : limites de fréquence, Retry-After et fausses alertes

Ce que signifie un 429 et ce qui l'accompagne

429 est défini dans la RFC 6585 comme le statut pour la limitation de fréquence : le client a envoyé trop de requêtes dans un laps de temps donné. La spécification laisse délibérément deux choses ouvertes : comment le serveur identifie le client, et comment les requêtes sont comptées. C'est pourquoi les limites de fréquence diffèrent tant d'un service à l'autre.

En pratique, les serveurs comptent par adresse IP, par clé API, par session, par compte, ou par combinaison de ceux-ci, et ils utilisent des fenêtres fixes, des fenêtres glissantes ou des seaux de jetons. Deux fréquences de requêtes identiques peuvent donc être acceptables sur un endpoint et bloquées sur un autre du même site.

La réponse porte les signaux dont vous avez besoin :

• Retry-After est le standard. La RFC 9110 autorise soit un nombre de secondes, soit une date HTTP, et un client bien élevé attend ce délai avant de retenter.
• Les en-têtes de limite de fréquence comme RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset, ou les variantes plus anciennes X-RateLimit-, exposent le budget et son moment de réinitialisation. Ce sont des conventions, pas une partie de la RFC 9110, donc vérifiez la documentation de l'API pour les noms exacts.
• Le corps devrait expliquer la limite en termes lisibles par un humain. Beaucoup d'API nomment quel quota a été dépassé, ce qui évite beaucoup de suppositions.

Un 429 n'est pas mis en cache par défaut, donc les intermédiaires ne devraient pas continuer à le servir une fois la fenêtre réinitialisée.

Limite de fréquence ou vraie panne ?

Ces deux cas sont constamment confondus, car les deux se manifestent par des requêtes échouées. Les tests qui les distinguent sont rapides :

• Le code lui-même. Une limite de fréquence répond 429. Un serveur surchargé ou en mode maintenance répond 503. Les deux peuvent porter Retry-After, ce qui explique pourquoi les gens les confondent, mais ils signifient des choses différentes : 429 dit « vous spécifiquement envoyez trop », 503 dit « le service dans son ensemble ne peut pas prendre de travail en ce moment ». Voir le guide du 503 pour ce côté-là.
• Le temps de réponse. Les limites de fréquence rejettent vite, généralement en millisecondes, car la décision est prise avant que tout vrai travail n'ait lieu. Une surcharge répond lentement ou expire.
• Qui est affecté. Une limite de fréquence touche une identité de client. Testez depuis une adresse IP différente ou avec une clé API différente : si cela réussit pendant que le client limité échoue toujours, c'est une limite, pas une panne.
• Le schéma dans le temps. La limitation de fréquence est périodique et se résout d'elle-même. Les échecs se regroupent, puis s'arrêtent exactement quand la fenêtre se réinitialise, puis reviennent. Une panne ne reprend pas poliment selon un horaire.
• La corrélation avec votre propre volume. Si les échecs ont commencé quand vous avez augmenté une fréquence de vérification, ajouté des travailleurs parallèles ou lancé une tâche par lots, la cause est de votre côté de la connexion.

Pourquoi la surveillance peut déclencher un 429 elle-même

La surveillance est une requête répétée depuis un petit ensemble d'adresses vers la même URL, ce qui est proche de la forme que les limiteurs de fréquence sont conçus pour attraper. Un intervalle de vérification très court aggrave cela, car des vérifications toutes les minutes multipliées par de nombreuses URL surveillées s'additionnent rapidement contre un budget par IP. Exécuter une vérification depuis de nombreux emplacements à la fois aggrave aussi les choses : l'origine voit une rafale plutôt qu'un filet régulier, et les limites de rafale se déclenchent en premier.

Le choix de l'URL compte aussi. Les pages de recherche, les endpoints d'API et tout ce qui écrit sont généralement limités plus sévèrement qu'une page d'accueil statique. Et si la surveillance et l'application partagent une clé API, les deux se disputent un seul quota. Le résultat est un moniteur qui signale le site comme défaillant alors que le site va parfaitement bien, et un limiteur de fréquence qui fait son travail correctement.

Comment corriger un 429

1. Lisez les en-têtes de réponse avant de changer quoi que ce soit :

   curl -sS -o /dev/null -D - https://example.com/api/items

   Retry-After et tout en-tête de limite de fréquence vous donnent le vrai budget, ce qui vaut mieux que de deviner des intervalles.
2. Respectez Retry-After. Retenter immédiatement prolonge le blocage dans de nombreuses implémentations. Attendez le délai indiqué.
3. Reculez de façon exponentielle avec du jitter dans le code client, pour que les clients concurrents ne se synchronisent pas et ne retentent pas en horde tonitruante.
4. Abaissez la fréquence de requêtes. Pour la surveillance, passez un endpoint surveillé à un intervalle plus long, ou échelonnez les vérifications pour que de nombreux emplacements ne se déclenchent pas à la même seconde.
5. Surveillez une URL peu coûteuse et représentative. Un endpoint de santé léger ou la page d'accueil vous dit que le site est en ligne sans dépenser le quota dont vous avez besoin pour le vrai trafic.
6. Exemptez le client de surveillance au niveau du limiteur. Mettez sur liste blanche les adresses des points de contrôle, ou donnez à la surveillance sa propre clé API avec son propre budget, pour qu'elle ne soit jamais en concurrence avec le trafic de production.
7. Si vous possédez le limiteur, vérifiez que la limite est correcte. Demandez-vous si le budget correspond à l'usage réel, s'il devrait être par compte plutôt que par IP, et si des proxys partagés ou du NAT d'entreprise mettent de nombreux utilisateurs derrière une seule adresse.

Surveiller les 429 sans les provoquer

Les limites de fréquence apparaissent généralement d'abord pour les clients les plus actifs, ce qui signifie que les clients payants et les intégrations les rencontrent avant quiconque de votre équipe. Une vérification HTTP programmée qui affirme le code de statut attendu montre un 429 comme un événement distinct et horodaté plutôt que comme des rapports épars de « l'API est instable », et le chronométrage vous dit si la limite est périodique ou permanente. Réglez l'intervalle délibérément : assez fréquent pour remarquer les problèmes rapidement, assez doux pour que la vérification ne soit jamais ce qui déclenche la limite. La famille plus large des refus, y compris 401 et 403, est couverte dans la vue d'ensemble des 4xx.