Erreur 401 authentication_error / invalid x-api-key — vérifications à effectuer, dans l’ordre

Presque toutes les erreurs 401 ont l’une de quatre causes, et une seule est « la clé est incorrecte ». Les trois autres laissent la clé parfaitement valide ; recréer la clé est donc souvent une perte de temps.

L’erreur

resposta (HTTP 401)

{
  "type": "error",
  "error": { "type": "authentication_error",
             "message": "invalid x-api-key" }
}

Causes et solutions en bref

Cause	Solution
En-tête incorrect pour l’hôte	Anthropic lit x-api-key ; la plupart des passerelles compatibles avec OpenAI lisent Authorization: Bearer. La même valeur placée dans le mauvais en-tête est interprétée comme absente.
Ancienne variable d’environnement résiduelle	Une ANTHROPIC_API_KEY oubliée dans le profil du shell peut prendre le pas sur celle que vous venez d’exporter.
Base URL modifiée sans modifier l’identifiant	Pointer vers un autre hôte ne rend pas la clé du fournisseur précédent valide sur celui-ci. L’hôte et l’identifiant doivent changer ensemble.
Espace, retour à la ligne ou guillemets dans la clé	Une copie depuis un PDF ou une conversation peut introduire des caractères invisibles. Vérifiez la longueur de la chaîne.

Vérifiez ce que contient réellement l’environnement

Avant de modifier quoi que ce soit, examinez les variables dans le même shell que celui qui exécute l’application. Dans un nombre étonnant de cas, deux identifiants sont définis simultanément, provenant de fournisseurs différents.

conferir.sh

for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s [%s] tamanho=%s\n' \
    "$v" "$(printenv "$v" | cut -c1-10)" "$(printenv "$v" | wc -c)"
done

Testez l’identifiant en dehors de l’application

Une requête directe permet de distinguer « l’hôte refuse la clé » de « l’application n’envoie pas la clé ». Si curl fonctionne et pas le code, le problème ne vient pas de l’identifiant.

testar.sh

curl -s -o /dev/null -w 'status=%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

# 200 -> credencial boa; investigue a aplicação
# 401 -> credencial ou cabeçalho errados para este host

Distinguez 401, 403 et 402

401 signifie « je ne sais pas qui vous êtes » : l’identifiant n’a pas été accepté. 403 signifie « je sais qui vous êtes, mais vous n’êtes pas autorisé » : vous êtes authentifié, sans permission. 402 signifie « je sais qui vous êtes, mais votre solde est insuffisant ». Seule l’erreur 401 se résout en modifiant l’identifiant.

Si vous appelez via Kunavo

Kunavo accepte la clé sk-kn- aussi bien dans Authorization: Bearer que dans x-api-key ; la base URL correspond à l’origine du site, sans aucun chemin supplémentaire. Avec Claude Code, utilisez ANTHROPIC_AUTH_TOKEN et ANTHROPIC_BASE_URL, car le token ne dépend pas de l’approbation unique exigée par ANTHROPIC_API_KEY, et supprimez explicitement ANTHROPIC_API_KEY — une ancienne valeur dans cette variable est la cause la plus fréquente d’une session qui semble configurée mais refuse malgré tout les requêtes. La procédure détaillée d’authentification se trouve dans la documentation d’authentification.

Questions fréquentes

Recréer la clé résout-il le problème ?

Uniquement si la clé a réellement été révoquée. Dans les trois autres causes courantes — mauvais en-tête, ancienne variable, base URL modifiée — la nouvelle clé échouera exactement de la même manière.

Un 401 peut-il être dû à un solde insuffisant ?

Non. Un solde insuffisant produit une erreur 402, avec un message mentionnant les crédits. L’erreur 401 concerne toujours l’identité.

Cela fonctionne avec curl mais échoue dans mon code. Pourquoi ?

Presque toujours parce que le code lit une autre variable d’environnement ou s’exécute dans un autre shell ou conteneur où l’export n’est pas arrivé. Affichez l’identifiant masqué depuis le processus pour le confirmer.

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.