API Claude : 529 overloaded_error — signification et solution correcte

Effectuer des nouvelles tentatives sans aggraver l’incident

Traitez la 529 comme une « 429 sans Retry-After ». Utilisez une temporisation exponentielle commençant à environ 2 secondes, avec gigue, plafonnée à 30–60 secondes ; après environ 5 tentatives, abandonnez et placez le travail en file d’attente. La gigue est l’élément déterminant : sans elle, tous les clients reviennent au même moment et prolongent précisément la surcharge dont ils cherchent à sortir.

Rediriger plutôt que faire échouer

Pour les chemins sensibles à la latence, préparez une chaîne de secours. Avec un endpoint compatible OpenAI, il suffit de modifier une chaîne de caractères — nul besoin d’ajouter un SDK ou un compte :

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          # 過負荷 — 次の候補へ
    raise last

Ne suspecter votre code qu’en dernier recours

Si seule une catégorie précise de requêtes reçoit une 529 alors que les autres appels au même moment aboutissent, il ne s’agit pas d’une panne générale. Vérifiez que ce chemin n’envoie pas un prompt anormalement volumineux et ne déclenche pas des appels en rafale dans une boucle courte. À l’inverse, si tous les appels reçoivent simultanément une 529 puis que le problème disparaît spontanément, la cause est la capacité. Dans ce cas, il faut corriger les nouvelles tentatives et le mécanisme de secours, pas refactoriser.

La 529 est-elle de ma faute ?

Non. Il s’agit d’un problème de capacité du fournisseur. Vos deux seules responsabilités sont de ne pas amplifier l’incident (temporisation et gigue) et de prévoir une voie de sortie lorsque l’incident dépasse la latence acceptable.

Quelle est la différence entre 529 et 429 ?

La 429 signifie que vous avez dépassé votre limite, tandis que le serveur fonctionne normalement. La 529 signifie que le serveur est en surcharge, tandis que votre limite et votre solde sont normaux. Les deux erreurs peuvent faire l’objet d’une nouvelle tentative, mais seule la 429 fournit l’indication Retry-After.

Combien de temps une 529 dure-t-elle généralement ?

C’est imprévisible et aucune durée ne peut être garantie. La bonne réponse est donc une temporisation plafonnée accompagnée d’une file d’attente, et non un délai d’attente fixe inscrit dans le code. Si ce chemin dispose d’un budget de latence, le mécanisme de secours prend le relais au lieu d’attendre.

Les appels échoués avec une 529 sont-ils quand même facturés ?

Ils ne sont pas facturés via Kunavo. Les requêtes qui se terminent par une erreur ne sont pas facturées. En contrat direct, les règles de facturation de chaque fournisseur s’appliquent.