Anthropic 529 overloaded_error : ce que cela signifie et comment le gérer

L’API Claude retourne 529 avec le type overloaded_error d’erreur lorsque l’API est temporairement surchargée. Selon Anthropic, cela peut se produire lorsque l’API rencontre un trafic élevé pour l’ensemble des utilisateurs. Votre demande est correcte. L’API est occupée, de sorte qu’elle a rejeté la requête. Lorsque votre organisation dépasse ses propres limites de débit, vous recevez un code 429 à la place. Le corps de la réponse a la même structure que pour toutes les autres erreurs de l'API Claude : un champ de premier niveau type dont la valeur est error, un objet error contenant les champs type et message, ainsi qu'un identifiant request_id que vous pouvez communiquer au support Anthropic. Pour plus d’informations, consultez les erreurs de l’API Claude.

529, 429 ou limite de dépense : comment les distinguer

L’API Claude utilise des erreurs d’apparence similaire pour des problèmes très différents. Certaines disparaissent si vous attendez. L'une d'elles ne disparaît qu'au début du mois prochain.

Une erreur 429 liée à un plafond de dépenses présente le même type d'erreur qu'une limitation de débit. Le code qui réessaie systématiquement chaque rate_limit_error continue donc d'échouer. Anthropic remarque que les nouvelles tentatives échouent jusqu'à ce que l'accès reprenne, y compris les nouvelles tentatives automatiques du Kit de développement logiciel (SDK). Pour plus d’informations, consultez Atteindre votre plafond de dépenses.

Comment gérer un 529

1. Vérifiez le code d’état avant de réessayer. Un 529 et un 429 nécessitent des délais d'attente différents, tandis qu'un 429 sans retry-after ne nécessite aucune nouvelle tentative.
2. Attendez avant de réessayer en cas d'erreur 529. Réessayez avec une temporisation exponentielle et une gigue aléatoire, puis arrêtez après quelques tentatives. Si la réponse contient un en-tête retry-after, attendez plutôt la durée indiquée.
3. Laissez le SDK effectuer les premières nouvelles tentatives. Les SDK officiels Anthropic réessaient deux fois par défaut en cas d'erreurs de connexion, de limitations de débit et d'erreurs 5xx, en appliquant un délai exponentiel, et respectent retry-after lorsque cet en-tête est présent. Vous pouvez modifier le nombre avec max_retries (maxRetries en TypeScript). Lorsque le SDK a épuisé ses tentatives, votre code reçoit l'erreur.
4. Arrêtez les nouvelles tentatives en cas de dépassement du plafond de dépenses. Si une erreur 429 ne comporte pas d'en-tête retry-after, informez l'utilisateur et configurez une alerte pour vous-même.
5. Gardez l’utilisateur informé. Mettre en file d’attente le travail et réessayer ultérieurement, ou afficher un message clair « occupé, réessayez dans une minute » au lieu d’une erreur générique.

Dans le sdk Python, une erreur 429 déclenche anthropic.RateLimitError et tout code d’état 500 ou supérieur, y compris 529, déclenche anthropic.InternalServerError:

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

Comment tester la gestion d'une erreur 529 par votre application

Vous rencontrez rarement une erreur 529 pendant le développement. Cela dépend du trafic de chaque utilisateur de l’API Claude. Vous ne pouvez donc pas le déclencher. La façon dont vous testez détermine si vous trouvez les bogues avant que vos utilisateurs ne le fassent.

Essayez-le dans votre application

Dev Proxy intercepte les requêtes https://api.anthropic.com de votre application et retourne des erreurs au format d'erreur d'Anthropic, tandis que votre application continue d'appeler l'URL réelle. Téléchargez un preset et démarrez Dev Proxy avec celui-ci :

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"

Aucun préréglage n’inclut un plafond de dépenses 429. Pour tester ce scénario, ajoutez une réponse sans en-tête retry-after au fichier anthropic-errors.json du préréglage :

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

Pour faire échouer toutes les requêtes et observer ce qui se passe lorsque le SDK a épuisé ses tentatives, démarrez Dev Proxy avec --failure-rate 100. Pour plus d’informations, consultez Le taux d’échec des demandes de modification. Pour installer Dev Proxy, consultez Configurer Dev Proxy.

Étapes suivantes

Voir aussi

• 429 Too Many Requests : signification et gestion de cette erreur
• Les erreurs 500, 502, 503 et 504 provenant d’API : ce qu’elles signifient et comment les gérer
• Qu’est-ce que le bridage ?
• Tester si mon application gère correctement la limitation de requêtes