Erreur 529 overloaded_error dans l’API Claude — signification et solutions

Le 529 est la seule erreur Claude que votre code n’a pas provoquée : Anthropic est elle-même en surcharge. Vous ne pouvez pas la corriger, mais vous pouvez bien l’absorber. Cela implique un retry patient, un modèle de secours et l’interdiction d’amplifier l’incident par des tentatives immédiates.

L’erreur

resposta (HTTP 529)

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

Causes et solutions en bref

Cause	Solution
Saturation du fournisseur (jours de lancement, incidents régionaux)	Backoff exponentiel avec jitter. Consultez la page d’état du fournisseur au lieu de relancer le déploiement.
Votre pic de trafic est survenu pendant un incident partiel	Répartissez les tâches par lots ; dix minutes d’attente suffisent généralement.
Retry immédiat en boucle	Réessayer immédiatement multiplie la charge et prolonge l’incident pour tout le monde, vous compris.

Effectuez vos retries de manière responsable

Traitez le 529 comme un 429 sans en-tête retry-after : backoff exponentiel commençant à environ 2 s, avec jitter, plafond de 30–60 s, abandon après environ 5 tentatives et mise en file de la tâche. Le même embranchement de code que pour 429 convient au 529.

retry.py

import time, random
from openai import APIStatusError

def com_retry(fn, tentativas=5):
    for i in range(tentativas):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            espera = min(2 ** i + random.random(), 60)
            time.sleep(espera)
    raise RuntimeError("esgotou as tentativas")

Changez de modèle plutôt que d’abandonner

Dans les parcours sensibles à la latence, définissez un modèle de secours : au sein d’une même famille (Sonnet → Haiku), le comportement reste similaire ; entre fournisseurs (Claude → GPT), vous survivez à un incident complet. Sur un endpoint compatible avec OpenAI, il suffit de modifier une chaîne.

failover.py

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

def completar(mensagens):
    ultimo = None
    for modelo in PREFERIDOS:
        try:
            return client.chat.completions.create(
                model=modelo, messages=mensagens, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            ultimo = e          # saturado — tenta o próximo
    raise ultimo

Ne confondez pas 529, 429 et 402

429 signifie que vous avez dépassé vos limites (le serveur va bien). 529 signifie que le serveur est surchargé (votre quota va bien). 402 signifie que le solde est insuffisant. Les trois se ressemblent dans les logs mais exigent des corrections complètement différentes : seuls 429 et 529 doivent être réessayés.

Si vous appelez via Kunavo

Chez Kunavo, le même catalogue multimodèle se trouve derrière une seule clé et un seul portefeuille ; le failover entre fournisseurs de l’exemple ci-dessus consiste donc à changer le nom du modèle, sans nécessiter de deuxième compte ni de nouvelle inscription. Les requêtes qui échouent ne sont pas facturées. La capacité et le prix sont deux questions distinctes ; pour la seconde, les tarifs par token sont indiqués dans la notre guide des tarifs de l’API Claude.

Questions fréquentes

L’erreur 529 est-elle de ma faute ?

Non. Il s’agit d’un problème de capacité du côté du fournisseur. Vos seules responsabilités sont de ne pas amplifier le problème (backoff avec jitter) et de disposer d’une solution de migration si l’incident dure plus longtemps que votre budget de latence.

Quelle est la différence entre 529 et 429 ?

429 signifie que vous avez dépassé vos limites ; 529 signifie que le serveur est surchargé. Les deux peuvent être réessayés, mais seul le 429 est généralement accompagné d’une indication retry-after.

Serai-je facturé pour une requête qui renvoie 529 ?

Cela ne devrait pas arriver : la requête n’a produit aucun token. Chez Kunavo, les requêtes échouées ne sont pas déduites du solde.

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.