Claude erreur 529 overloaded_error — cause et stratégie de retry

529 est la seule erreur Claude que votre code n'a pas causée : c'est Anthropic qui est saturé. Vous ne pouvez pas la corriger — seulement l'absorber proprement. Cela veut dire des reprises patientes avec backoff, un modèle de secours sur les chemins sensibles à la latence, et surtout pas de rafales de retry immédiats qui amplifient l'incident.

L’erreur

réponse (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

Causes et solutions en un coup d’œil

Cause	Solution
Saturation côté fournisseur (jours de lancement, incidents régionaux). Touche tous les clients au même moment.	Backoff avec jitter ; consultez la page de statut d'Anthropic plutôt que de redéployer votre application.
Votre propre pic de charge tombe sur une capacité déjà tendue.	Étalez les traitements par lots ; dix minutes de décalage suffisent en général.
Confusion avec 429 : dans les logs, une limite de débit ressemble à ça, mais la cause n'a rien à voir.	429 veut dire que vous avez dépassé vos limites (le serveur va bien) ; 529 veut dire que le serveur est saturé (votre quota va bien). Seul 429 est accompagné d'un indice Retry-After.
Aucun repli défini, donc un problème du fournisseur remonte jusqu'à l'utilisateur final.	Définissez une chaîne de repli — dans la même famille (Sonnet → Haiku) le comportement reste proche ; entre fournisseurs (Claude → Gemini) vous survivez à un incident complet.

Reprendre sans amplifier l'incident

Traitez 529 comme un 429 sans Retry-After : backoff exponentiel à partir de ~2 secondes, avec jitter, plafonné à 30–60 secondes, abandon après environ cinq tentatives et mise en file d'attente du travail. Le jitter est la partie qui compte : sans lui, tous les clients reviennent en même temps et prolongent exactement la saturation qu'ils cherchent à fuir.

Basculer plutôt que tomber

Sur les chemins sensibles à la latence, définissez une chaîne de repli. Sur un point d'entrée compatible OpenAI, c'est une seule chaîne de caractères à changer — pas de second SDK, pas de second compte :

failover.py

PREFERRED = ["claude-sonnet-4-6", "claude-haiku-4-5", "gemini-2-5-flash"]

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # saturé — passer au palier suivant
    raise last

Et seulement ensuite, regarder votre code

Si les 529 n'apparaissent que sur un seul type de requête pendant que les autres appels passent au même moment, ce n'est pas un incident généralisé : vérifiez si ce chemin envoie des prompts inhabituellement gros ou tire en boucle serrée. Si au contraire cela touche tous les appels d'un coup puis disparaît tout seul, c'était de la capacité — et le travail appartient au retry et au repli, pas à une refonte.

Si vous appelez via Kunavo

Kunavo achemine Claude par plus d'un chemin amont, et son catalogue multi-modèles fait du basculement entre fournisseurs un simple changement de nom de modèle sur la même clé et le même portefeuille — le schéma ci-dessus n'a pas besoin d'un second compte. Les 529 qui vous parviennent malgré tout ne sont jamais facturés. Capacité et prix sont deux questions distinctes ; pour la seconde, les tarifs par modèle sont dans la grille tarifaire de l'API Claude.

Questions fréquentes

Une 529, est-ce de ma faute ?

Non. C'est de la capacité côté fournisseur. Vos seules responsabilités sont de ne pas amplifier l'incident (backoff, jitter) et d'avoir une sortie de secours si l'incident dure plus longtemps que votre budget de latence.

529 ou 429 — quelle différence ?

429 signifie que vous avez dépassé vos limites, le serveur va bien. 529 signifie que le serveur lui-même est saturé, votre quota va bien. Les deux sont rejouables ; seul 429 apporte un indice Retry-After.

Combien de temps dure une période de 529 ?

Ce n'est pas prévisible et cela ne se garantit pas — c'est pourquoi la bonne réponse est un backoff plafonné plus une file d'attente, et non un délai écrit en dur dans le code. Si votre chemin a un budget de latence, c'est le repli qui prend le relais plutôt que l'attente.

Les appels en 529 sont-ils facturés ?

Via Kunavo, non : une requête qui se termine en erreur n'est pas facturée. En contrat direct, cela dépend des règles de facturation du fournisseur concerné.

Guides associés

La sémantique complète des erreurs se trouve dans la référence des erreurs ; obtenir une clé prend une minute via créer un compte et la documentation d’authentification.

Erreur 529 overloaded_error de l'API Claude — ce que c'est et comment l'absorber