Claude Code « API Error: bad_response_status_code » — lire le statut sous-jacent

Cette erreur indique que l’appel a échoué et ne dit presque rien sur la raison. Les informations utiles — le code de statut et le message du fournisseur — sont accessibles avec un seul indicateur de débogage, et chaque statut pointe vers une correction différente.

L’erreur

terminal

API Error: bad_response_status_code

(no status, no provider message — the wrapper hides both)

Causes et solutions en bref

Cause	Solution
401 / 403 sous-jacent	Incompatibilité d’identifiants ou d’en-têtes avec une URL de base personnalisée. Vérifiez quelle variable d’authentification est définie.
404 sous-jacent	Soit l’identifiant du modèle est inconnu de cet hôte, soit l’URL de base comporte un segment de chemin supplémentaire.
402 sous-jacent	Le portefeuille de la passerelle est vide. Rechargez-le ; la configuration du client n’est pas en cause.
429 / 529 sous-jacent	Limitation de débit ou saturation de l’amont. Réessayez avec un délai exponentiel plutôt que de reconfigurer.
Un corps non JSON avec un 200	Un portail captif, un proxy d’entreprise ou une page d’erreur. Le statut peut être correct alors que le corps reste inutilisable.

Transformer l’enveloppe en véritable erreur

La sortie de débogage de Claude Code affiche la requête et la réponse de l’amont. Exécutez un appel en échec avec cette option activée et lisez la ligne de statut — tout le reste dépend de ce qu’elle indique.

debug.sh

claude --debug 2>&1 | tee claude-debug.log

grep -iE 'status|http/|error' claude-debug.log | head -20

Reproduire le même appel avec curl

Sortez l’URL de base et l’identifiant de l’outil, puis envoyez directement la requête. Cela permet de distinguer en une étape « l’hôte nous rejette » de « le client est mal formé » — et le corps brut nomme généralement le problème en termes simples, contrairement à l’enveloppe qui l’a supprimé.

reproduce.sh

curl -i "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Vérifier que l’URL de base ne comporte aucun chemin final

Claude Code ajoute son propre chemin `/v1/...`. Une URL de base qui se termine déjà par `/v1` produit `/v1/v1/messages`, ce à quoi tout hôte répond par un 404 — à nouveau encapsulé sous la forme bad_response_status_code. Définissez uniquement l’origine.

base-url.sh

# Wrong — doubles the version segment
export ANTHROPIC_BASE_URL="https://api.kunavo.com/v1"

# Right — origin only
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

Si vous appelez via Kunavo

Avec Kunavo, les deux statuts à reconnaître immédiatement sont 402 et 401 : 402 signifie que le portefeuille ne peut pas couvrir la requête — c’est un problème de solde, pas de configuration — et 401 signifie que Kunavo n’a pas reçu de clé sk-kn- utilisable. La clé est lue depuis Authorization: Bearer ou x-api-key ; vérifiez donc ce que Claude Code a réellement envoyé : une clé dans ANTHROPIC_API_KEY nécessite une approbation unique dans une session interactive et est ignorée si elle est refusée, tandis que ANTHROPIC_AUTH_TOKEN est utilisée immédiatement. Les deux statuts renvoient un corps JSON qui indique la raison, le journal de débogage est donc décisif et non simplement indicatif. Les requêtes qui échouent ne sont pas facturées. La variable à définir et la raison sont expliquées dans le guide des variables d’authentification.

Questions fréquentes

Cette erreur peut-elle vraiment être un bug de Claude Code ?

Rarement. Il s’agit d’une enveloppe de niveau transport : quelque chose a répondu, et la réponse n’était pas un succès. Une reproduction avec curl permet de trancher — si curl échoue également, le client n’est pas en cause.

Cela fonctionne avec l’API officielle, mais pas avec ma passerelle.

La différence vient donc de l’identifiant ou de l’URL de base, pas de l’outil. Vérifiez l’en-tête d’authentification attendu par la passerelle et si votre URL de base contient déjà /v1.

Dois-je réessayer automatiquement ?

Uniquement après avoir identifié le statut. Réessayer un 401 ou un 404 est inutile ; réessayer un 429 ou un 529 avec un délai exponentiel est approprié.

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.