Claude Code « API Error: 401 authentication_error » avec une URL de base personnalisée

Ici, une erreur 401 concerne vos identifiants ou votre URL de base, jamais votre modèle — un problème de modèle renvoie 404 avec un message nommant le modèle. Cette seule distinction permet de résoudre la plupart des cas avec un seul curl.

L’erreur

terminal

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Missing or invalid API key"}}

Causes et solutions en bref

Cause	Solution
ANTHROPIC_API_KEY définie alors qu’ANTHROPIC_AUTH_TOKEN était attendue	Utilisez AUTH_TOKEN pour une URL de base tierce ; API_KEY déclenche une demande d’autorisation unique.
URL de base contenant un chemin /v1	Définissez uniquement l’origine — Claude Code ajoute lui-même /v1/messages.
Clé révoquée ou compte suspendu	Les deux cas répondent 401, jamais 403. Générez une nouvelle clé et vérifiez le compte.
Modèle non fourni par l’endpoint Messages	Cela renvoie 404 en nommant le modèle, et non 401 : la correction est donc différente.

Affichez les trois variables et vérifiez que l’URL de base ne contient aucun chemin

La cause la plus fréquente est visible ici. L’URL de base doit être une origine — sans /v1 ni chemin final — car le client ajoute lui-même l’endpoint. Une URL de base se terminant par /v1 produit une requête vers /v1/v1/messages.

check-env.sh

env | grep -E '^ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY|MODEL)='

# Right: https://api.kunavo.com
# Wrong: https://api.kunavo.com/v1

Appelez directement l’endpoint, des deux manières

Le endpoint /v1/messages de Kunavo accepte l’identifiant dans x-api-key ou Authorization: Bearer, raison pour laquelle Claude Code n’a besoin ni de plugin ni de proxy en amont. Si curl réussit et pas le CLI, le problème vient de votre environnement shell, pas du serveur.

probe.sh

curl -s https://api.kunavo.com/v1/messages   -H "x-api-key: $ANTHROPIC_AUTH_TOKEN"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-sonnet-5","max_tokens":8,
       "messages":[{"role":"user","content":"hi"}]}'

# Same call, other header style — both are accepted:
#   -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Désactivez la variable que vous n’utilisez pas

Si ANTHROPIC_API_KEY et ANTHROPIC_AUTH_TOKEN sont toutes deux définies, la mauvaise peut être utilisée. Désactivez ANTHROPIC_API_KEY, ouvrez un nouveau shell et réessayez — une exportation obsolète dans un profil shell survit à toutes les autres corrections.

Si le statut est 404, cessez de déboguer la clé

Une erreur 404 dont le message nomme le modèle signifie que les identifiants ont été acceptés, mais pas le nom du modèle. Corrigez plutôt ANTHROPIC_MODEL ; la clé n’est pas en cause. Lors d’une nouvelle configuration, la cause habituelle est qu’aucun modèle n’est défini : Claude Code envoie alors sa valeur par défaut intégrée, le dernier Opus, que Kunavo ne propose peut-être pas encore ; et /model sonnet demande Sonnet 5.5, que Kunavo ne propose pas — définissez ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL et ANTHROPIC_DEFAULT_SONNET_MODEL avec des identifiants provenant de GET /v1/models.

Si vous appelez via Kunavo

Un 401 de Kunavo se réduit à cinq causes : aucune clé n’est arrivée dans Authorization: Bearer ou x-api-key, la clé ne porte pas le préfixe sk-kn-, il s’agit d’une clé sk-kn- que Kunavo n’a jamais émise (faute de frappe ou copie tronquée), elle a été révoquée ou le compte est suspendu. Aucune de ces situations ne renvoie 403 ; le code d’état seul indique donc la famille concernée. Une clé valide ciblant un modèle non fourni par l’endpoint Messages renvoie 404 et nomme le modèle dans le message, pas 401. Voilà tout l’arbre de diagnostic.

Questions fréquentes

Pourquoi ma clé fonctionne-t-elle avec curl mais pas avec Claude Code ?

Presque toujours à cause d’une seconde variable définie dans un profil shell ou d’une URL de base contenant un chemin. L’endpoint accepte les deux styles d’en-tête ; la différence ne vient donc pas de l’en-tête.

ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY ?

AUTH_TOKEN pour une URL de base tierce : il est utilisé immédiatement. API_KEY déclenche d’abord une demande d’autorisation unique, souvent prise pour un échec.

Un abonnement Claude couvre-t-il une URL de base personnalisée ?

Non. Un abonnement authentifie l’accès à l’endpoint du fournisseur ; si vous redirigez le CLI ailleurs, il utilise les identifiants de cet endpoint, facturés par celui-ci.

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.

Claude Code « API Error: 401 authentication_error » avec une URL de base personnalisée — toutes les causes