Les erreurs de l'API Claude se répartissent en trois familles : identifiants et format de requête, limitation de débit et capacité, longueur de contexte. L'ordre de traitement doit être : d'abord le code HTTP et le type d'erreur, ensuite l'identifiant de requête, et seulement en dernier le prompt. Dans l'ordre inverse, on prend facilement un problème de configuration pour un problème de modèle.

Cet article traite séparément les 401, 429, les 529 overloaded et les dépassements de contexte, avec les causes, les étapes de diagnostic et un code de backoff réutilisable. Les modèles et les prix sont ceux de la page Tarifs des modèles.

Remarque : Anthropic et Claude sont des marques de leurs détenteurs respectifs. Les types d'erreur et le comportement des interfaces peuvent évoluer ; cet article décrit les situations courantes d'octobre 2026 et la documentation officielle fait foi.

1. Regardez d'abord le code de statut, pas le prompt

Code Type d'erreur Signification courante Réessayer ?
400 invalid_request_error Paramètre, format ou longueur de contexte incorrect Corriger la requête puis réessayer
401 authentication_error Clé absente, erronée ou expirée Non, corriger d'abord les identifiants
403 permission_error Clé sans droit sur le modèle ou le projet Non, vérifier les droits
404 not_found_error Chemin ou nom de modèle incorrect Non, consulter la documentation
413 request_too_large Corps de requête trop volumineux Découper puis réessayer
429 rate_limit_error Fréquence, concurrence ou tokens au-delà de la limite Réessayer avec un backoff
500 api_error Erreur interne du serveur Réessayer avec un backoff
529 overloaded_error Serveur en surcharge Réessayer avec un backoff

Conservez le request-id présent dans les en-têtes de réponse. Pour un diagnostic auprès du prestataire, un identifiant de requête vaut mieux que dix captures d'écran. Les journaux doivent au minimum contenir l'heure, le code de statut, le type d'erreur, le nom du modèle et l'identifiant de requête ; n'y écrivez jamais la clé complète ni de contenu sensible.

2. 401 : vérifier l'en-tête, puis la clé

Un 401 signifie que l'identité n'a pas été validée ; cela n'a rien à voir avec le solde ou les capacités du modèle. Procédez dans cet ordre :

  1. Utilisez-vous x-api-key plutôt que Authorization: Bearer ? L'en-tête d'authentification de Claude Messages API n'est pas Bearer.
  2. L'en-tête anthropic-version: 2023-06-01 est-il présent ? Son absence produit parfois un 400, mais mieux vaut le renseigner d'emblée.
  3. La clé comporte-t-elle un espace, un saut de ligne ou des guillemets superflus ? C'est le problème le plus fréquent lors d'un copier-coller.
  4. La variable d'environnement est-elle réellement chargée ? Affichez seulement le préfixe, jamais la clé complète dans les journaux.
  5. La clé a-t-elle été révoquée, et appartient-elle à l'organisation ou au projet courant ?
  6. L'URL de base pointe-t-elle vers le bon environnement, avec le chemin /v1/messages ?
export ANTHROPIC_API_KEY="sk-votre_cle"

curl "https://ai.zhongshangqihang.com/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Réponds uniquement OK"}]
  }'

Un code 200 sur cette commande confirme que la clé, l'URL de base et le nom du modèle fonctionnent. Si un 401 persiste, testez la même clé sur un autre point d'entrée pour distinguer un problème de clé d'un problème de configuration de passerelle ou de réseau. Les noms de modèles sont ceux de la page Tarifs des modèles.

3. 429 : une limitation de débit, pas un « solde insuffisant »

Un 429 indique que la requête dépasse une limite de débit ou de quota. Situations fréquentes :

  • Nombre de requêtes ou de tokens par minute dépassé.
  • Pic de concurrence qui sature le quota en peu de temps.
  • Plusieurs services partagent une même clé et se disputent le quota.
  • Les retries n'ont pas de backoff et amplifient l'échec, créant une tempête.
  • Une sortie longue consomme beaucoup de tokens de sortie et réduit la marge de concurrence.
Symptôme Cause possible Traitement
429 concentrés aux heures de pointe Pic de trafic File d'attente et lissage
429 avec une clé partagée Quota mutualisé Séparer les clés par projet
Aggravation après retry Retries sans backoff Backoff exponentiel avec gigue
429 sur les requêtes longues en premier Tokens de sortie élevés Réduire max_tokens ou la concurrence

Regardez d'abord le retry-after de la réponse s'il existe, puis décidez du délai. Le SDK distingue RateLimitError et APIStatusError : utilisez le type, pas une correspondance de chaîne sur le message.

import random
import time
from anthropic import Anthropic, APIStatusError, RateLimitError

client = Anthropic()

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.messages.create(
                model="claude-sonnet-5-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.content[0].text
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, tentative {attempt + 1}, attente de {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}, nouvelle tentative dans {wait:.1f}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Nombre de tentatives épuisé")

Le retry ne convient qu'aux erreurs transitoires. Pour une opération ayant déjà produit des effets de bord, vérifiez avec une clé d'idempotence ou un contrôle d'état si elle a été exécutée avant de décider de la renvoyer.

4. 529 overloaded : une surcharge serveur, pas votre quota

Un 529 overloaded_error indique une charge serveur trop élevée, généralement indépendante de votre propre usage. Le traitement diffère du 429 : pour un 429, vérifiez d'abord votre concurrence et votre quota ; pour un 529, vérifiez l'état du service et réduisez la pression.

  1. Confirmez que le type d'erreur est overloaded_error et ne le prenez pas pour une clé invalide.
  2. Conservez le request-id et l'heure pour aider le prestataire à localiser l'incident.
  3. Appliquez un backoff exponentiel avec gigue aléatoire et un nombre maximal de tentatives, sans retries à intervalle fixe.
  4. Réduisez la concurrence, lissez la charge et suspendez temporairement les tâches non critiques si nécessaire.
  5. Préparez un modèle ou un canal de secours, en acceptant une variation de qualité côté métier.
  6. Si la durée dépasse le prévu, contactez le prestataire avec l'identifiant de requête.

Un retry fixe à une seconde transforme une petite panne en avalanche. La stratégie de retry doit avoir une limite et des alertes, sans boucle infinie.

5. Dépassement de contexte : mesurer avant de découper

Un dépassement de contexte renvoie généralement un 400 invalid_request_error, avec un message contenant prompt is too long. Le modèle n'est pas en panne : le budget entrée plus sortie dépasse la fenêtre de contexte du modèle.

Les sources courantes sont : historique non tronqué, sortie d'outil renvoyant un journal entier, document inséré en entier, images trop nombreuses, prompt système trop long. Procédez dans cet ordre :

  1. Quantifiez l'entrée avec count_tokens avant la requête, sans estimer au nombre de caractères.
  2. Tronquez l'historique le plus ancien en conservant le system, les derniers tours et un résumé.
  3. Faites d'abord une recherche pour ne récupérer que les extraits pertinents, sans verser toute la base.
  4. Découpez les documents longs par chapitre, traitez par segments puis fusionnez les résultats.
  5. Compressez la sortie des outils pour ne renvoyer que les champs nécessaires, sans rapporter la réponse complète à chaque tour.
  6. Laissez de la place à la sortie. max_tokens est la limite de sortie, mais entrée et sortie doivent tenir ensemble dans le contexte.
import os
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-5-5"
LIMIT = int(os.environ.get("CONTEXT_BUDGET", "200000"))  # budget interne, pas la limite du modèle

def fit_messages(messages):
    while client.messages.count_tokens(model=MODEL, messages=messages).input_tokens > LIMIT:
        if len(messages) <= 2:
            raise ValueError("Un message dépasse à lui seul le budget, découper le document")
        messages = messages[2:]  # retire le tour user/assistant le plus ancien
    return messages

Ici, LIMIT est un budget défini par l'équipe, pas une spécification du modèle. Le fixer un peu en dessous de la limite du modèle laisse une marge pour la sortie et les appels d'outils.

6. Tableau récapitulatif du diagnostic

  1. Notez le code de statut, le type d'erreur, le request-id, le nom du modèle et l'heure.
  2. Pour 401 et 403, vérifiez identifiants et droits ; pour 404, le chemin et le nom du modèle.
  3. Pour 400, vérifiez les paramètres, la longueur du contexte, le format des images et la taille du corps.
  4. Pour 429, vérifiez le quota, la concurrence, le partage de clé et les tempêtes de retries.
  5. Pour 529, vérifiez l'état du service, appliquez un backoff, réduisez la concurrence et préparez la dégradation.
  6. Pour 500, appliquez un backoff puis contactez le prestataire avec l'identifiant de requête si le problème persiste.
  7. Après chaque incident, complétez la supervision et les alertes au lieu d'attendre le retour des utilisateurs.

Questions fréquentes

Quelle différence entre 429 et 529 ?

Un 429 signifie que votre requête dépasse un débit ou un quota : vérifiez votre concurrence, vos clés et votre usage. Un 529 indique une surcharge du serveur : appliquez un backoff, réduisez la concurrence et consultez l'état du service. Les deux appellent un retry, mais le diagnostic diffère.

Pourquoi les retries échouent-ils encore ?

Il manque peut-être un backoff, la concurrence est trop élevée, plusieurs services partagent une clé, ou la requête est elle-même un 400. Le retry ne règle que les erreurs transitoires, pas les erreurs de paramètres ni de droits.

prompt is too long signifie-t-il que le modèle est défaillant ?

Non. Cela indique que l'entrée dépasse la fenêtre de contexte. Quantifiez avec count_tokens, puis tronquez l'historique, découpez le document ou faites de la recherche ; n'ajoutez pas de prompt supplémentaire.

Combien de tentatives faut-il prévoir ?

Il n'existe pas de chiffre universel : fixez une limite selon la tolérance métier, par exemple 3 à 5, puis dégradez ou alertez. L'intervalle doit croître avec une gigue aléatoire pour éviter des renvois simultanés.

Comment distinguer une erreur de passerelle d'une erreur officielle ?

Regardez le type d'erreur et le request-id, puis envoyez la même requête au point d'entrée officiel et à celui de la passerelle. Vous distinguerez rapidement un problème de clé, de réseau, de configuration de passerelle ou de service amont.

Pour aller plus loin

Créez d'abord une clé de test sur ZSQH AI Gateway, exercez une fois les cas 401, 429, 529 et dépassement de contexte, puis branchez la supervision de production. La disponibilité des modèles et les prix sont ceux de la page Tarifs des modèles.

Articles liés :