Erreur Claude 529 overloaded_error — cause et stratégie correcte de nouvelles tentatives

Le 529 est la seule erreur Claude que votre code n’a pas provoquée : Anthropic est lui-même en surcharge. Vous ne pouvez pas la corriger, seulement la gérer correctement. Cela signifie des nouvelles tentatives patientes avec backoff, un modèle de secours pour les chemins sensibles à la latence et surtout pas de tempêtes immédiates de nouvelles tentatives qui aggraveraient encore l’incident.

L’erreur

Antwort (HTTP 529)

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

Causes et solutions en bref

Cause	Solution
Surcharge côté fournisseur (jours de lancement, incidents régionaux). Elle touche tous les clients simultanément.	Backoff avec jitter ; consultez la page d’état d’Anthropic au lieu de redéployer votre application.
Votre propre pic de charge rencontre une capacité déjà sous tension.	Répartissez les tâches par lots ; un délai de dix minutes suffit généralement à résorber la situation.
Confusion avec le 429 : une limite de débit ressemble dans les logs, mais sa cause est totalement différente.	429 signifie que vous avez dépassé vos limites (le serveur est sain) ; 529 signifie que le serveur est surchargé (votre quota est correct). Seul le 429 fournit un indice Retry-After.
Aucun secours n’est défini, de sorte qu’un problème du fournisseur se propage jusqu’à l’utilisateur final.	Définissez une chaîne de secours — au sein de la même famille (Sonnet → Haiku), le comportement reste similaire ; entre fournisseurs (Claude → GPT), vous pouvez également survivre à une panne complète.

Réessayer sans aggraver l’incident

Traitez le 529 comme un 429 sans Retry-After : backoff exponentiel à partir d’environ 2 secondes, avec jitter, plafonné à 30–60 secondes ; après environ cinq tentatives, abandonnez et placez le travail dans une file. Le jitter est essentiel : sans lui, tous les clients reviennent en même temps et prolongent précisément la surcharge qu’ils cherchent à résorber.

Contourner plutôt que tomber en panne

Pour les chemins sensibles à la latence, définissez une chaîne de secours. Sur un endpoint compatible avec OpenAI, il s’agit d’une seule chaîne de caractères à modifier — pas de deuxième SDK ni de deuxième compte :

failover.py

PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

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          # überlastet — nächste Stufe versuchen
    raise last

Vérifiez ensuite votre propre code

Si le 529 n’apparaît que pour un seul type de requête et que les autres appels passent au même moment, il ne s’agit pas d’une panne généralisée du fournisseur : vérifiez si ce chemin envoie des prompts inhabituellement volumineux ou s’exécute dans une boucle serrée. S’il apparaît simultanément sur tous les appels puis disparaît spontanément, il s’agissait d’un problème de capacité — le travail doit alors être géré par retry et fallback, pas par un refactoring.

Si vous appelez via Kunavo

Kunavo achemine Claude par plusieurs chemins amont, et son catalogue multi-modèles transforme le basculement entre fournisseurs en un simple changement de nom de modèle avec la même clé et la même facturation — le pattern ci-dessus ne nécessite pas de deuxième compte. Les erreurs 529 qui vous parviennent malgré tout ne sont jamais facturées. Capacité et prix sont deux questions distinctes ; pour la seconde, les tarifs par modèle figurent dans la grille tarifaire de l’API Claude.

Questions fréquentes

Le 529 est-il de ma responsabilité ?

Non. Il s’agit d’un problème de capacité côté fournisseur. Votre responsabilité se limite à ne pas aggraver l’incident (backoff, jitter) et à disposer d’une cible de secours si l’incident dure plus longtemps que votre budget de latence.

529 ou 429 — quelle est la différence ?

429 signifie que vous avez dépassé vos limites ; le serveur est sain. 529 signifie que le serveur lui-même est surchargé ; votre quota est correct. Les deux erreurs peuvent faire l’objet de nouvelles tentatives, mais seul le 429 fournit un indice Retry-After.

Combien de temps dure généralement une phase 529 ?

C’est imprévisible et impossible à garantir — la bonne réponse est donc un backoff plafonné associé à une file, et non un délai d’attente inscrit dans le code. Si votre chemin dispose d’un budget de latence, le fallback prend le relais au lieu d’attendre.

Les appels 529 échoués sont-ils facturés ?

Pas sur Kunavo : une requête qui se termine par une erreur n’est pas facturée. Avec un contrat direct, cela dépend des règles de facturation du fournisseur concerné.

Guides associés

La sémantique détaillée des erreurs est disponible dans référence des erreurs ; obtenir une clé prend une minute via inscription et la guide d’authentification.