Sommaire
Avez-vous déjà été interrompu en pleine tâche dans Claude Code par une erreur de ce genre ?
API Error: 529 {"type":"error","error":
{"type":"overloaded_error","message":"Overloaded"}}
# ou
API Error: 500 Internal server error.529 Overloaded signifie que l'API d'Anthropic est temporairement en surcapacité (saturée), et 500 signifie qu'une erreur inattendue s'est produite à l'intérieur du serveur. Les deux sont côté serveur — et, surtout, il ne s'agit ni d'une erreur dans votre requête ou vos réglages, ni de votre quota d'usage épuisé. La documentation officielle l'indique sans détour : « un 529 n'est pas votre limite d'usage et n'est pas décompté de votre quota ». Autrement dit, ce sont des erreurs qui se résolvent généralement en « patientant un instant puis en réessayant ».
Les points clés d'emblée. (1) 529/500 sont côté serveur — ce n'est pas de votre faute (et ne consomment pas votre quota). (2) Claude Code réessaie déjà automatiquement jusqu'à 10 fois avec un backoff exponentiel avant de vous afficher quoi que ce soit — quand le message convivial apparaît, ces tentatives sont déjà épuisées. (3) La solution, c'est « vérifier la page de statut → patienter → changer de modèle avec /model ». La capacité est suivie par modèle, donc même quand Opus est saturé, Sonnet passe souvent.
C'est côté serveur, pas de votre faute
— Claude Code réessaie déjà avant de vous afficher quoi que ce soit
La solution, c'est donc « patienter et réessayer / basculer avec /model / vérifier status.claude.com ».
Il n'y a pour ainsi dire aucun code ni réglage à corriger.
1. Ce que cette erreur vous indique
HTTP 529 (overloaded_error / message « Overloaded ») indique que l'API d'Anthropic est temporairement en surcapacité. La description officielle dit littéralement que « l'API est temporairement en surcharge » et que cela « peut se produire lorsque les API connaissent un trafic élevé pour l'ensemble des utilisateurs ». Cela signifie non pas la faute d'une personne en particulier, mais que la demande globale a brièvement dépassé l'offre.
HTTP 500 (api_error) est une erreur interne inattendue du côté d'Anthropic. La documentation précise qu'elle n'est « pas causée par votre prompt, vos réglages ou votre compte ». Apparenté, le 504 (timeout_error) survient quand une requête longue arrive à expiration (à noter qu'Anthropic documente le 504, tandis que 502/503 proviennent généralement d'infrastructures en amont comme les passerelles).
Le point crucial : « 529 et 500 sont des problèmes côté serveur et ne consomment pas votre quota d'usage. » Ils sont totalement distincts du usage limit reached lié au quota de votre offre et de votre propre limite de débit 429 (nous les départageons au §4). Il n'y a donc aucune raison de vous crisper et de corriger du code ou des réglages — par défaut, c'est « patienter et réessayer ».
2. Claude Code réessaie déjà pour vous
En réalité, avant même que vous ne voyiez le message d'erreur, Claude Code a déjà réessayé en coulisses. Selon la documentation officielle —
Le comportement de réessai automatique
Les erreurs serveur, les réponses de surcharge (overloaded), les expirations de requête, les limitations 429 temporaires et les connexions interrompues sont toutes réessayées jusqu'à 10 fois avec un backoff exponentiel. Pendant les tentatives, l'indicateur affiche un compte à rebours Retrying in Ns · attempt x/y. Au moment où la chaîne conviviale API Error: apparaît, ces 10 tentatives sont épuisées.
Ainsi, « un 529 a clignoté mais ça a continué » est normal — le réessai automatique l'a absorbé. À l'inverse, si vous atteignez le message convivial (« Repeated 529 Overloaded errors … try again in a moment. If it persists, check https://status.claude.com »), c'est le signe que la charge est suffisamment forte pour que même les tentatives n'aient pas suffi à rétablir la situation. Vous pouvez ajuster les réessais avec CLAUDE_CODE_MAX_RETRIES (par défaut 10) et le plafond par requête avec API_TIMEOUT_MS (par défaut 600000 ms = 10 minutes) — baissez le nombre pour échouer vite dans les scripts, augmentez-le pour traverser un incident plus long.
3. Ce que vous pouvez faire
Les gestes face à un 529/500 sont en fait très simples. Essayez-les dans l'ordre.
Patienter, basculer, vérifier
/feedback (joignez le request_id pour accélérer l'enquête).
Vous hésitez ? 1) patienter → 2) basculer avec /model → 3) vérifier le statut.
Décaler vers des heures creuses aide aussi. Il n'y a pour ainsi dire aucun réglage à corriger.
À noter : le message « Server is temporarily limiting requests » est lui aussi officiellement décrit comme « une limitation côté serveur de courte durée, sans rapport avec votre limite d'usage. » Il se résorbe lui aussi après une brève attente et constitue quelque chose de différent du usage limit lié au quota de l'offre.
4. La distinguer des erreurs voisines
La famille « ça s'est arrêté » peut avoir des causes opposées. Commencez par séparer selon « côté serveur ou de votre côté ? »
| Erreur | Le problème de qui | Consomme du quota ? | Principale solution |
|---|---|---|---|
| 529 Overloaded | Côté serveur (capacité, touche tout le monde) | Non | Patienter & réessayer, /model, vérifier le statut |
| 500 / 504 | Côté serveur (erreur interne / expiration) | Non | Réessayer ; si persistant, /feedback |
| 429 Rate limit | De votre côté (limite de débit de votre clé API) | Oui (votre débit) | Ralentir, monter de palier, attendre le retry-after |
| usage limit reached | De votre côté (allocation de l'offre Pro/Max) | Oui (offre) | Attendre la réinitialisation ; solutions |
| 400 Invalid request | De votre côté (une requête incorrecte) | Non | Corriger le corps de la requête |
Un moyen mnémotechnique : 5xx (529 inclus) est côté serveur = ça se résout en patientant. 429 et usage limit concernent votre « quantité » = ajustez le débit ou l'offre. 400 concerne votre « contenu » = corrigez la requête. 429 et 529 sont particulièrement faciles à confondre, mais 429 comporte un en-tête retry-after et consomme du quota, tandis que 529 n'a pas d'en-tête et ne consomme aucun quota — ce sont des choses différentes. Pour les autres erreurs courantes de Claude Code, voir le récapitulatif des erreurs.
5. Pour les développeurs (API/SDK)
Si vous faites tourner votre propre application sur l'API/SDK, la bonne conception traite 529/500 comme « un événement passager qui peut normalement se produire ».
(1) Les SDK officiels lèvent des exceptions typées (OverloadedError, InternalServerError, etc.) et réessaient automatiquement les erreurs transitoires avec un backoff exponentiel — interceptez les classes d'exception, pas des correspondances de chaînes. (2) Si vous réessayez vous-même, utilisez « backoff exponentiel + jitter ». (3) L'en-tête retry-after est présent sur le 429 mais PAS sur le 529, donc sur un 529 patientez avec votre propre backoff, et non selon un délai dicté par l'en-tête. (4) Prévoyez un modèle de repli (Claude Code dispose de --fallback-model). (5) Montez le trafic progressivement pour éviter la « limite d'accélération » du 429 après un pic d'usage. Si vous avez besoin d'une disponibilité stable, le Priority Tier et la Message Batches API sont aussi des options. Pour les bases, voir Qu'est-ce qu'une API d'IA.
6. Pic passager ou incident ?
Le même 529/500 signifie des choses différentes selon qu'il s'agit d'« un pic qui disparaît instantanément » ou « une panne continue qui se répète ».
Un pic passager (un ou quelques-uns qui se résolvent au réessai) reste dans la plage normale des fluctuations de la demande. Le réessai automatique l'absorbe généralement, et il n'y a rien à corriger de votre côté. En revanche, « Repeated 529 », ou un 500 qui survit aux réessais, est un signe pour soupçonner un incident en cours — vérifiez d'abord status.claude.com, et si une panne est signalée, attendre le rétablissement est le seul bon geste. Si un 500 persiste sans incident signalé, signalez-le via /feedback avec le request_id. Dans tous les cas, tout ce qu'un utilisateur peut faire face à un 529/500, c'est « réessayer, basculer avec /model, vérifier le statut et signaler » — et c'est réellement suffisant.
Résumé
Les « API Error: 529 Overloaded » et « 500 Internal server error » de Claude Code sont des événements côté serveur où l'API d'Anthropic est temporairement en surcharge ou a rencontré une erreur interne. Ce n'est ni une erreur dans votre requête ou vos réglages, ni votre quota d'usage épuisé, et ils ne consomment aucun quota. Claude Code réessaie automatiquement jusqu'à 10 fois avec un backoff exponentiel avant de vous afficher quoi que ce soit ; le message convivial signifie que ces tentatives sont épuisées.
La solution est simple : (1) patienter et réessayer -> (2) changer de modèle avec /model (la capacité est par modèle) -> (3) vérifier status.claude.com -> (4) /feedback si un 500 persiste. Ils sont différents du 429 (votre débit) et du usage limit (votre offre), et le 529 ne comporte pas de retry-after. Les développeurs devraient concevoir autour avec le réessai automatique du SDK, le backoff exponentiel + jitter et un modèle de repli. Si cela se répète, soupçonnez un incident et vérifiez la page de statut — dans tous les cas, il n'y a pour ainsi dire aucun code ni réglage à corriger. À lire aussi : solutions pour usage limit, comparatif Opus/Sonnet/Haiku, récapitulatif des erreurs de Claude Code.
FAQ
Q. « 529 Overloaded » est-il causé par quelque chose que j'ai mal fait, ou par mon code ?
A. Non — c'est un problème côté serveur. Un 529 signifie que l'API d'Anthropic est temporairement en surcapacité (congestion touchant tous les utilisateurs) ; votre requête, vos réglages et votre compte ne sont pas en cause. La documentation l'indique sans détour : « un 529 n'est pas votre limite d'usage et n'est pas décompté de votre quota. » Cela se résout généralement si vous patientez un instant puis réessayez.
Q. On me dit sans cesse de réessayer — dois-je marteler la commande moi-même ?
A. En général non. Claude Code réessaie déjà automatiquement jusqu'à 10 fois avec un backoff exponentiel avant d'afficher l'erreur (Retrying in Ns · attempt x/y). Le message convivial est apparu parce que ces 10 tentatives ont été épuisées. Patientez un peu, et pour un long prompt il suffit de taper « réessaie » pour le relancer avec le contexte d'origine. Vous pouvez ajuster le nombre avec CLAUDE_CODE_MAX_RETRIES.
Q. Quelle est la différence entre 529 et 429 ?
A. 529 est une surcharge côté serveur (touche tout le monde ; ne consomme aucun de vos quotas), tandis que 429 est votre propre limite de débit (vous avez dépassé le RPM, etc. de votre clé API — il s'agit de votre allocation de débit). Un indice : 429 comporte un en-tête retry-after, alors que 529 n'en a pas. Un 429 requiert un ajustement de votre côté (ralentir, monter de palier) ; un 529 ne demande qu'à patienter et réessayer ou basculer avec /model.
Q. Pourquoi basculer avec /model fonctionne-t-il parfois ?
A. Parce que la capacité (la congestion) est suivie par modèle. Même si Opus est en forte charge, Sonnet peut passer instantanément s'il a de la marge. Claude Code lui-même invite parfois à basculer en cas de charge (« Opus is experiencing high load, please use /model to switch to Sonnet »). Quand vous êtes pressé, basculer vers un modèle plus léger ou différent avec /model est un contournement rapide.
Q. Je reçois 529/500 sans arrêt. Que dois-je faire ?
A. Soupçonnez un incident en cours et vérifiez status.claude.com. Si une panne est signalée, tout ce que vous pouvez faire est d'attendre le rétablissement. Si un 500 persiste sans incident signalé, signalez-le via /feedback avec le request_id pour qu'Anthropic puisse enquêter. Comme 529/500 sont des événements côté serveur, il n'y a pour ainsi dire aucun code ni réglage à corriger de votre côté.
