Erreur 429 de l’API Claude : attendre ne suffit pas toujours

Pour corriger durablement une erreur 429 de l’API Claude, commencez par identifier la ressource saturée : requêtes, jetons d’entrée, jetons de sortie ou capacité d’accélération. Attendre selon le délai reçu peut rendre la prochaine tentative possible, mais une charge inchangée risque d’épuiser aussitôt le même budget.

Le diagnostic repose sur le message d’erreur, l’en-tête retry-after et les en-têtes de limite de débit. Ce résultat détermine ensuite s’il faut lisser les appels, réduire leur concurrence, alléger les entrées, contenir les sorties ou augmenter progressivement le trafic.

Une 429 ne désigne pas un compteur unique

Le statut 429 indique que trop de requêtes ont été envoyées pendant une période donnée. La définition normalisée du statut 429 autorise un en-tête Retry-After, mais ne fixe ni la manière d’identifier le client ni celle de compter son utilisation.

Claude applique à l’API Messages des budgets distincts de requêtes par minute (RPM), de jetons d’entrée par minute (ITPM) et de jetons de sortie par minute (OTPM). Le centre d’aide d’Anthropic précise que ces plafonds dépendent du palier d’utilisation et sont définis au niveau de l’organisation.

Une hausse brutale du trafic peut en outre déclencher une limite d’accélération. Un simple délai ne répond donc qu’à la question « quand réessayer » : il ne dit pas encore quelle caractéristique de la charge doit changer.

Lire les en-têtes avant de modifier les reprises

La documentation des limites de débit de Claude indique qu’une 429 décrit la limite dépassée et fournit retry-after, exprimé en secondes. Elle documente aussi les familles anthropic-ratelimit-requests-*, anthropic-ratelimit-input-tokens-* et anthropic-ratelimit-output-tokens-*, avec des valeurs de plafond, de capacité restante et de reconstitution.

Enregistrez ces en-têtes avec le modèle utilisé, l’organisation ou l’espace de travail, l’heure, le nombre d’appels actifs et la consommation de jetons des requêtes voisines. Les valeurs remaining proches de zéro désignent le compartiment sous pression ; les valeurs reset indiquent quand sa capacité sera entièrement reconstituée.

Si les compteurs de requêtes, d’entrée et de sortie conservent de la marge, examinez le message de la 429 et l’évolution récente du trafic. Une montée très rapide de la charge rend la limite d’accélération plausible ; augmentez alors le débit par paliers plutôt que de chercher uniquement un compteur épuisé.

Faire correspondre la correction au budget saturé

• RPM : placez les appels dans une file partagée, plafonnez leur cadence et lissez leur départ. Une moyenne conforme sur une minute ne protège pas nécessairement contre une rafale, car la limite peut être appliquée sur des intervalles plus courts.
• ITPM : retirez le contexte inutile et évitez de renvoyer les mêmes documents ou instructions. Pour la plupart des modèles Claude, les jetons lus depuis le cache ne comptent pas dans l’ITPM, contrairement aux nouvelles entrées et aux jetons écrits dans le cache ; cette exception doit être vérifiée pour le modèle employé.
• OTPM : réduisez la quantité de texte demandée lorsque le besoin le permet et limitez les générations simultanées. Ce sont les jetons effectivement produits qui alimentent ce compteur, pas la valeur de max_tokens considérée comme une réservation.
• Accélération : augmentez graduellement le trafic et conservez une file globale. Le but est d’éviter un passage soudain d’une faible activité à une charge élevée.

Le régulateur doit couvrir le périmètre où le quota est partagé. Si plusieurs processus appliquent chacun une limite locale sans coordination, leur somme peut dépasser le plafond de l’organisation ou celui configuré pour un espace de travail.

Un budget pratique peut suivre trois dimensions par groupe de modèles : appels lancés, jetons d’entrée estimés et jetons de sortie observés. Réservez une marge pour les variations de taille et recalez les estimations avec les données d’utilisation renvoyées par les réponses réussies.

Construire une reprise sans recréer la rafale

Lors d’une 429, utilisez retry-after comme attente minimale. Après des échecs successifs, appliquez une temporisation exponentielle bornée, puis ajoutez une variation aléatoire afin que les workers suspendus au même moment ne repartent pas tous ensemble.

À titre d’exemple indicatif, une base d’une seconde peut produire des fenêtres maximales de 1, 2, 4 puis 8 secondes. Chaque worker choisit une attente dans la fenêtre, sans reprendre avant retry-after ; le plafond, l’échéance totale et le nombre de tentatives dépendent de la latence acceptable pour la tâche.

Les règles de reprise des SDK officiels prévoient déjà deux nouvelles tentatives par défaut pour les défaillances transitoires, avec temporisation exponentielle et respect de retry-after lorsqu’il est présent. Ce nombre est configurable : vérifiez cette couche avant d’ajouter une boucle applicative, faute de quoi les deux mécanismes peuvent cumuler les appels et les délais.

Fixez enfin une échéance absolue et un nombre maximal de tentatives. Les travaux qui dépassent ces bornes doivent rejoindre une file d’échec observable plutôt que repartir indéfiniment.

Valider le réglage sous une charge progressive

1. Reproduisez d’abord la charge à faible concurrence et conservez le message de la 429, les en-têtes, le modèle et les volumes de jetons.
2. Augmentez un seul facteur à la fois : cadence, concurrence, taille des entrées ou longueur des sorties.
3. Repérez le premier compteur dont la capacité restante s’épuise, puis réduisez la variable correspondante.
4. Provoquez plusieurs reprises contrôlées pour vérifier que les workers partageant le quota respectent la même échéance et redémarrent de façon échelonnée.

Suivez séparément le taux de 429, les reprises par appel, le temps en file, la concurrence et les débits de jetons d’entrée et de sortie. Si la charge utile reste durablement proche du plafond après lissage et réduction des volumes, une augmentation de limite peut devenir nécessaire ; elle ne remplace pas une politique de reprise bornée.

À lire aussi:

• Google My Activity : effacer le compte ne vide pas le navigateur