Lorsque Claude Code utilise une API tierce, la plupart des erreurs ne viennent pas du modèle, mais de la configuration, de l'authentification ou du réseau : un 401 dès la mise en place, un 404 après changement d'URL de base, un 429 au milieu d'une tâche, ou une tâche longue bloquée jusqu'au délai d'attente. L'ordre de traitement consiste à lire le code de statut et le type d'erreur, puis le request-id, et à ne modifier le prompt qu'en dernier recours. Cet article traite séparément les 401, 404, 429, le dépassement de contexte et les délais, avec des étapes de diagnostic, une liste de journaux et des exemples de code. Modèles et facturation font foi sur la page Tarifs des modèles.

Remarque : Claude, Claude Code et Anthropic sont des marques de leurs détenteurs respectifs. Les types d'erreur et le comportement des interfaces peuvent changer selon les versions ; cet article décrit les cas courants d'octobre 2026 et la documentation officielle reste la référence finale.

1. Localiser la couche où survient l'erreur

Une requête traverse quatre couches : client, réseau, passerelle et modèle amont. Un même 401 peut venir d'une clé erronée ou d'un en-tête d'authentification incompatible ; un même 404 peut venir d'un /v1 en trop ou d'un nom de modèle inexistant. Isolez d'abord la couche pour éviter de modifier la configuration dans la mauvaise direction.

Code Type d'erreur Cause fréquente Traitement
400 invalid_request_error Paramètres, format, longueur de contexte ou plafond de dépenses Corriger la requête ou le plafond, puis réessayer
401 authentication_error Clé absente, erronée, expirée, en-tête incompatible Corriger les identifiants, ne pas réessayer
402 billing_error Problème de facturation ou d'informations de paiement Vérifier la facturation
403 permission_error Clé sans droit sur le modèle ou le projet Vérifier les droits
404 not_found_error Chemin ou nom de modèle incorrect Vérifier l'URL de base et le nom du modèle
413 request_too_large Corps de requête au-delà de la limite Découper la requête
429 rate_limit_error Fréquence, concurrence ou plafond de dépenses Réessayer après temporisation
500 api_error Erreur interne du serveur Réessayer avec temporisation
504 timeout_error Délai de traitement dépassé Passer en flux ou découper
529 overloaded_error Serveur surchargé Temporiser, réduire la concurrence

Conservez le request-id des en-têtes de réponse ; le corps d'erreur contient souvent aussi un request_id. Pour le support, un ID de requête vaut mieux que dix captures d'écran. Journalisez au minimum l'heure, le code, le type d'erreur, le nom du modèle et l'ID de requête ; jamais la clé complète ni de contenu sensible.

2. 401 et 403 : en-têtes d'authentification et 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. Claude Code possède deux variables faciles à confondre : ANTHROPIC_API_KEY, envoyée comme X-Api-Key, et ANTHROPIC_AUTH_TOKEN, envoyée comme Authorization: Bearer. Si la passerelle n'accepte qu'un seul mode, utiliser l'autre provoque un 401 systématique ; vérifiez l'exigence et n'exportez pas les deux simultanément.

Autres causes courantes : espaces, retours à la ligne, guillemets ou caractères pleine largeur autour de la clé ; clé supprimée, expirée ou appartenant à un autre espace de travail ; URL de base pointant vers le mauvais environnement ; connexion par abonnement et clé API définies ensemble ; réseau d'entreprise ou proxy réécrivant l'en-tête d'authentification.

Un 403 est généralement un problème de droits : modèle non ouvert à la clé, absence de droit sur le projet, blocage par liste blanche IP, ou politique d'espace de travail. Ne réessayez pas un 403 : vérifiez d'abord les droits sur les modèles et la politique d'accès dans la console.

Pour isoler rapidement : appelez directement /v1/messages avec la même clé et la même URL de base. Si l'appel direct réussit mais que Claude Code échoue, le problème vient de la configuration du client ; si l'appel direct échoue aussi, il vient de la clé, de la passerelle ou du réseau.

3. 404 : chemin de l'URL de base et nom du modèle

Un 404 recouvre deux cas : chemin incorrect ou ressource inexistante. Claude Code utilise l'API Anthropic Messages et configure généralement l'URL de base à la racine, le client ajoutant /v1/messages. Si l'URL de base contient déjà /v1, le chemin effectif peut devenir /v1/v1/messages.

Diagnostic dans l'ordre :

  1. Confirmez le protocole : Claude Code utilise Anthropic Messages, pas OpenAI Chat Completions.
  2. Vérifiez si l'URL de base a un /v1 en trop ou en moins. Claude Code prend généralement l'adresse racine ; un client compatible OpenAI prend généralement une adresse terminée par /v1.
  3. Vérifiez la barre oblique finale et la casse, pour éviter les doubles barres ou une troncature du chemin.
  4. Copiez le nom de modèle actuel depuis la page Tarifs des modèles ; les alias de passerelle peuvent différer des noms d'origine.
  5. Testez avec une requête minimale pour écarter le proxy et le cache du client.

Si le message est model not found, vérifiez le nom du modèle et les droits. Si c'est not_found_error avec un chemin manifestement incorrect, vérifiez l'URL de base.

4. 429 : limitation, quota et tempête de reprises

Un 429 indique un dépassement de la limite de fréquence, de concurrence ou de dépenses. Causes courantes : nombre de requêtes ou de jetons par minute dépassé ; plusieurs services partageant une clé ; reprises sans temporisation formant une tempête ; plafond de dépenses du compte ou de l'espace de travail atteint ; montée soudaine du trafic déclenchant une limitation accélérée.

Certains 429 liés au plafond de dépenses n'incluent pas de retry-after : attendre ne rétablit pas la situation, il faut ajuster la limite ou recharger. Lisez d'abord retry-after ; s'il existe, attendez la durée indiquée. Sinon, appliquez un backoff exponentiel avec gigue aléatoire et fixez un nombre maximal de reprises. Ne réessayez pas les 401, 403, 404 et 400.

Attention aux reprises par défaut du SDK : le SDK officiel Anthropic réessaie deux fois les erreurs de connexion, les 429 et les 5xx. Si votre couche métier ajoute ses propres reprises, le nombre réel de requêtes s'additionne. Planifiez max_retries et les reprises métier ensemble.

429 et 529 diffèrent : pour un 429, vérifiez d'abord votre concurrence, vos clés et vos quotas ; un 529 signale une surcharge serveur, à traiter par temporisation, réduction de concurrence et consultation de l'état du service.

5. 400 et 413 : dépassement de contexte et requête trop volumineuse

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

Ordre de traitement :

  1. Quantifiez l'entrée avec count_tokens avant l'envoi, sans estimer au nombre de caractères.
  2. Tronquez l'historique le plus ancien et ne gardez que le system, les derniers tours et un résumé.
  3. Faites d'abord une recherche documentaire pour ne récupérer que les extraits pertinents, plutôt que la base entière.
  4. Découpez les documents longs par chapitre, traitez par segments puis fusionnez.
  5. Compressez les sorties d'outils pour ne renvoyer que les champs nécessaires.
  6. Laissez de la place à la sortie. max_tokens n'est qu'un plafond de sortie et ne résout pas un dépassement d'entrée.

Le 413 request_too_large concerne un corps de requête trop volumineux, ce qui diffère de la longueur de contexte. Les images inlinées en base64 dépassent facilement la limite : compressez-les, utilisez une interface d'envoi de fichier ou découpez la requête.

Tous les 400 ne sont pas des problèmes de contexte. Un paramètre non pris en charge par le modèle, une configuration de réflexion invalide ou un plafond de dépenses peuvent aussi renvoyer 400. Lisez le type et les champs précis du message.

6. Délais et coupures de flux : streaming, proxy et SSL

Le délai d'une requête Claude Code est contrôlé par API_TIMEOUT_MS, par défaut 600000 millisecondes, soit dix minutes. Sur un réseau lent ou derrière un proxy, augmentez-le modérément, sans le rendre infini : une panne mettrait alors très longtemps à apparaître.

Pour les tâches longues, privilégiez la sortie en flux ou les interfaces par lots. Une requête non streamée qui dépasse dix minutes peut voir sa connexion inactive coupée, avec un blocage ou un délai d'attente. Une requête en flux reçoit des données en continu et reste plus stable.

Attention : une requête en flux peut renvoyer HTTP 200, puis émettre un événement error dans le flux SSE. Un client qui ne lit que le code de statut considérera l'échec comme un succès. Analysez les événements d'erreur du flux et marquez la partie déjà générée comme incomplète.

Les problèmes de proxy et de certificat se manifestent aussi comme des délais : un proxy d'entreprise nécessite HTTPS_PROXY ou HTTP_PROXY ; une inspection TLS d'entreprise impose de faire confiance au certificat de l'autorité correspondante, souvent via NODE_EXTRA_CA_CERTS pour les clients Node. DNS, IPv6, pare-feu et MTU peuvent aussi déstabiliser la connexion : changez de réseau ou testez un partage mobile pour trancher rapidement. Si le premier octet de la passerelle est lent, surveillez CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.

7. Journaux et liste pour le support

Ne vous contentez pas de « ça plante ». Rassemblez les informations suivantes :

  1. Heure, fuseau horaire et durée de l'incident.
  2. Sortie de claude --version et système d'exploitation.
  3. URL de base (domaine seul, sans clé complète).
  4. Nom du modèle, mode flux ou non, durée de la requête et nombre de reprises.
  5. Code HTTP, type d'erreur et message complet.
  6. request-id, présent dans les en-têtes et parfois dans le corps.
  7. Périmètre : une personne, un réseau, un projet ou toute l'équipe.
  8. Reproduction minimale : une commande curl ou un dépôt minimal, et le résultat de la même requête vers l'entrée d'origine.

Le masquage doit être concret : conservez les quatre premiers et quatre derniers caractères de la clé, et traitez prompts et code selon les règles internes.

8. Exemple : décider des reprises selon le type d'erreur

L'exemple ci-dessous ne réessaie que les 429, les 5xx et les délais réseau ; les 401 et 404 échouent immédiatement pour éviter de transformer un problème de configuration en tempête de reprises. L'URL de base et le nom du modèle sont lus dans l'environnement.

import os
import random
import time

from anthropic import (
    Anthropic,
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
)

client = Anthropic(
    base_url=os.environ["ANTHROPIC_BASE_URL"],
    auth_token=os.environ["ANTHROPIC_AUTH_TOKEN"],
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.messages.create(
                model=os.environ["ANTHROPIC_MODEL"],
                max_tokens=512,
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.content[0].text
        except AuthenticationError as exc:
            raise SystemExit(f"401 : vérifiez la clé et l'en-tête, request-id={exc.request_id}") from exc
        except NotFoundError as exc:
            raise SystemExit(f"404 : vérifiez l'URL de base et le modèle, request-id={exc.request_id}") from exc
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429 : nouvelle tentative dans {wait:.1f}s")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError):
            wait = min(2 ** attempt, 10) + random.random()
            print(f"Délai ou connexion échouée : nouvelle tentative dans {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("Reprises épuisées : passer en mode dégradé ou alerter")

print(ask("Réponds seulement OK"))

Si la passerelle utilise X-Api-Key plutôt que Bearer, remplacez auth_token= par api_key= ou adaptez selon la documentation du client. L'exemple ne fixe pas max_retries ; le SDK applique donc ses reprises par défaut. En production, configurez-les de façon cohérente.

Questions fréquentes

Un 401 signifie-t-il toujours une clé erronée ?

Non. Un en-tête d'authentification incompatible, une URL de base pointant vers le mauvais environnement ou un proxy réécrivant les en-têtes renvoient aussi 401. Testez d'abord en direct avec la même clé et la même URL de base, puis examinez les variables du client.

Le 404 persiste après changement de modèle, que faire ?

Vérifiez surtout le chemin de l'URL de base. Claude Code prend généralement l'adresse racine et le client ajoute /v1/messages ; une adresse contenant déjà /v1 produit un double /v1. Vérifiez ensuite que le nom du modèle correspond à la liste de la passerelle.

Un 429 se résorbe-t-il toujours en attendant ?

Pas toujours. Une limitation de fréquence se résorbe généralement, mais un 429 déclenché par un plafond de dépenses peut ne pas contenir de retry-after ; attendre ne sert alors à rien, il faut ajuster la limite ou recharger. Lisez le type d'erreur et les en-têtes avant de décider.

Une requête en flux qui renvoie 200 puis s'interrompt est-elle un succès ?

Non. Une réponse en flux peut émettre un événement d'erreur SSE après le 200. Le client doit analyser le flux, confirmer la réception d'un événement de fin normal, sinon marquer le résultat comme incomplet et réessayer ou alerter.

Plus de reprises signifie-t-il plus de stabilité ?

Non. Les reprises ne corrigent que les erreurs transitoires ; un nombre excessif amplifie la panne et le coût. Fixez un plafond, un backoff exponentiel et une gigue, distinguez les erreurs réessayables des autres, et pour les opérations à effet de bord, vérifiez si elles ont déjà été exécutées avant de renvoyer.

Étape suivante

Créez une clé de test sur ZSQH AI Gateway, entraînez-vous une fois sur les 401, 404, 429 et délais, puis branchez la supervision de production. La disponibilité des modèles et la facturation figurent sur la page Tarifs des modèles.

Pour aller plus loin :

Remarque : Claude, Claude Code et Anthropic sont des marques de leurs détenteurs respectifs. Les types d'erreur et le comportement des interfaces peuvent évoluer ; la documentation officielle fait foi.