API Claude 401 authentication_error / invalid x-api-key

Un 401 de Claude correspond toujours à l’un de cinq problèmes : mauvais en-tête, mauvais type de clé pour le point de terminaison, variable d’environnement mal formée, clé révoquée ou mauvaise URL de base pour cette clé. Exécutez le diagnostic ci-dessous et vous trouverez le vôtre en moins d’une minute.

L’erreur

response (HTTP 401)

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

Causes et solutions en bref

Cause	Solution
Mauvais en-tête pour le point de terminaison	L’API native d’Anthropic attend x-api-key + anthropic-version ; les points de terminaison compatibles OpenAI attendent Authorization: Bearer.
Incompatibilité clé/point de terminaison	Les clés sk-ant-… ne fonctionnent qu’avec api.anthropic.com ; les clés de passerelle (par ex. sk-kn-…) ne fonctionnent qu’avec leur propre URL de passerelle.
Espaces ou guillemets introduits dans la variable d’environnement	Réexportez sans guillemets ni retours à la ligne ; affichez len(key) pour détecter un \n final dû au copier-coller.
Clé révoquée ou espace de travail désactivé	Créez une nouvelle clé dans la console et faites-la tourner dans votre gestionnaire de secrets.

Reproduire avec curl brut (retire votre SDK de l’équation)

Si curl fonctionne mais pas votre application, le bug se trouve dans la gestion de votre environnement, pas dans la clé :

diagnose.sh

# Native Anthropic wire (works on api.anthropic.com and Kunavo /v1/messages)
curl -s https://api.kunavo.com/v1/messages \
  -H "x-api-key: $KUNAVO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# OpenAI-compatible wire (Bearer header instead)
curl -s https://api.kunavo.com/v1/chat/completions \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Check the key isn't carrying whitespace
python3 -c "import os; k=os.environ['KUNAVO_API_KEY']; print(repr(k[:12]), len(k))"

Faire correspondre le préfixe de la clé à l’URL de base

sk-ant-… → api.anthropic.com. sk-kn-… → api.kunavo.com/v1. Envoyer une clé de passerelle à Anthropic (ou l’inverse) provoque toujours un 401 — le message d’erreur ne dit jamais « mauvais hôte », ce problème passe donc facilement inaperçu.

Faites tourner la clé si elle a déjà touché un dépôt ou un journal

Si la clé est correcte mais toujours rejetée, partez du principe qu’elle a été révoquée (les scanners automatisés révoquent rapidement les clés divulguées). Créez-en une nouvelle et stockez-la dans un gestionnaire de secrets plutôt que dans des fichiers .env susceptibles d’être validés.

Si vous appelez via Kunavo

Les clés Kunavo (sk-kn-…) s’authentifient avec l’un ou l’autre en-tête sur tous les points de terminaison — Authorization: Bearer, comme l’envoient les SDK OpenAI, ou x-api-key, comme le font les SDK Anthropic — ; quel que soit le SDK utilisé, seule l’URL de base change. Les clés sont créées et révoquées instantanément dans le tableau de bord. Une fois la clé authentifiée, les tarifs appliqués sont indiqués dans le grille tarifaire de l’API Anthropic Claude.

Questions fréquentes

Pourquoi ma clé fonctionne-t-elle avec curl mais pas dans mon application ?

Presque toujours à cause de la gestion de l’environnement : retour à la ligne final dû au copier-coller, guillemets inclus dans la valeur, variable non exportée vers le processus ou environnement différent chargé en production. Affichez la représentation et la longueur de la clé dans le processus défaillant.

Puis-je utiliser ma clé Anthropic Console sur une passerelle compatible OpenAI ?

Non. Chaque service n’authentifie que ses propres clés : les clés sk-ant appartiennent à api.anthropic.com, et les clés de passerelle à la passerelle. Obtenez une clé auprès de l’URL de base appelée.

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.

API Claude 401 authentication_error / invalid x-api-key — toutes les causes