Accueil / Quand ça déraille

Erreurs d'API et limite de débit

Un appel à l'API échoue de plusieurs façons différentes : une erreur 400 ou 404 signale le plus souvent une requête mal formée qui doit être corrigée avant tout nouvel essai, sauf le cas particulier d'un 400 renvoyé pour un plafond de dépense atteint, tandis qu'une erreur 429 ne se résout en attendant que si elle porte un en-tête Retry-After, ce qui n'est pas le cas d'un plafond de dépense atteint.

Une erreur renvoyée par l'API Anthropic porte un code de statut qui distingue des causes très différentes. Une erreur 400, invalid_request_error, ou 404, not_found_error, signale une requête mal formée : un paramètre invalide, un contenu incorrect, ou un identifiant de modèle qui n'existe plus tel quel. Réessayer cet appel sans le corriger reproduit la même erreur indéfiniment, la seule sortie est de recaler l'appel sur la spécification en vigueur. Un identifiant de modèle qui a changé de nom depuis la rédaction d'un script explique une bonne partie de ces erreurs 400 et 404 : la documentation actuelle du modèle en vigueur reste la première chose à ouvrir avant de soupçonner autre chose. Un 400 n'est cependant pas toujours une requête mal formée : l'API rend aussi ce code quand l'usage atteint un plafond de dépense fixé pour l'organisation ou l'espace de travail, sauf sur l'espace de travail Claude Code qui peut alors renvoyer un 429 à la place. Dans ce cas précis, corriger la requête ne sert à rien, c'est le plafond lui même qu'il faut relever.

Toutes les erreurs 429 ne se résolvent pas en attendant

Une erreur 429, rate_limit_error, signale un plafond atteint, mais deux plafonds distincts produisent ce même code. Un débit temporaire dépassé porte un en-tête Retry-After et se résout en respectant le délai qu'il indique avant de réessayer. Un plafond de dépense atteint pour un palier ne porte, lui, aucun en-tête Retry-After : la documentation le dit sans détour, un tel 429 échoue sans relâche jusqu'à ce que l'accès soit rétabli. Patienter face à une telle réponse ne sert à rien : continuer à réessayer dans ce cas gaspille des appels pour rien et retarde la vraie solution, relever le plafond fixé par l'organisation avant de reprendre l'envoi des requêtes.

HTTP/1.1 429 Too Many Requests
retry-after: 12

{"type":"error","error":{"type":"rate_limit_error"}}

La présence ou l'absence de cet en-tête, pas le seul code 429, tranche entre attendre et agir autrement.

Dans Claude Code, deux variables pilotent les nouvelles tentatives

Une erreur 529, overloaded_error, affiche dans Claude Code un message signalant que l'API est à pleine capacité, sans entamer le quota d'usage de la session. Cette précision compte : une série de 529 peut inquiéter sans pour autant grignoter le volume d'usage que l'abonnement autorise. Claude Code retente automatiquement les erreurs 429 et 529 de type débit temporaire, jamais les 429 de plafond de dépense d'une passerelle. CLAUDE_CODE_MAX_RETRIES borne le nombre de tentatives, CLAUDE_CODE_RETRY_WATCHDOG permet de retenter indéfiniment en session non surveillée : la figure qui accompagne cette leçon en donne les valeurs exactes.

Décider s'il faut patienter ou agir revient déjà dans une commande bloquée, où le même choix se pose face à un silence qui peut annoncer un blocage réel ou un travail encore en cours.