Un 401 de Claude siempre se debe a una de cinco cosas: el encabezado incorrecto, el tipo de clave incorrecto para el endpoint, una variable de entorno mal formada, una clave revocada o una URL base incorrecta para esa clave. Ejecuta el diagnóstico siguiente y encontrarás la causa en menos de un minuto.
El error
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}Causas y soluciones de un vistazo
| Causa | Solución |
|---|---|
| Encabezado incorrecto para el endpoint | La API nativa de Anthropic requiere x-api-key + anthropic-version; los endpoints compatibles con OpenAI requieren Authorization: Bearer. |
| Incompatibilidad entre clave y endpoint | Las claves sk-ant-… solo funcionan contra api.anthropic.com; las claves de gateway (por ejemplo, sk-kn-…) solo funcionan contra la URL de su propio gateway. |
| Espacios en blanco o comillas introducidos en la variable de entorno | Vuelve a exportar sin comillas ni saltos de línea; imprime len(key) para detectar un \n final procedente de copiar y pegar. |
| Clave revocada o espacio de trabajo deshabilitado | Genera una clave nueva en la consola y rótala en tu gestor de secretos. |
Reproduce el problema con curl sin procesar (elimina tu SDK de la ecuación)
Si curl funciona pero tu aplicación no, el error está en la gestión de variables de entorno, no en la clave:
# 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))"Haz coincidir el prefijo de la clave con la URL base
sk-ant-… → api.anthropic.com. sk-kn-… → api.kunavo.com/v1. Enviar una clave de gateway a Anthropic (o viceversa) siempre produce un 401; el mensaje de error nunca dice "host incorrecto", por lo que esta causa puede pasar desapercibida.
Rota la clave si alguna vez estuvo en un repositorio o registro
Si la clave es correcta y aun así se rechaza, supone que fue revocada (los escáneres automatizados revocan rápidamente las claves filtradas). Genera una nueva y guárdala en un gestor de secretos, en lugar de archivos .env que puedan confirmarse en un repositorio.
Si llamas a través de Kunavo
Las claves de Kunavo (sk-kn-…) se autentican con cualquiera de los dos encabezados en todos los endpoints: Authorization: Bearer, como las envían los SDK de OpenAI, o x-api-key, como hacen los SDK de Anthropic. Por tanto, uses el SDK que uses, solo cambia la URL base. Las claves se crean y revocan al instante en el panel. Una vez autenticada la clave, las tarifas que se aplican están en lista de precios de la API de Anthropic Claude.
Preguntas frecuentes
¿Por qué mi clave funciona con curl pero no en mi aplicación?
Casi siempre se debe a la gestión de variables de entorno: un salto de línea final al copiar y pegar, comillas incluidas en el valor, la variable no exportada al proceso o una variable de entorno diferente cargada en producción. Imprime la representación y la longitud de la clave dentro del proceso que falla.
¿Puedo usar mi clave de Anthropic Console en un gateway compatible con OpenAI?
No. Cada servicio autentica únicamente sus propias claves: las claves sk-ant pertenecen a api.anthropic.com y las claves de gateway pertenecen al gateway. Obtén una clave de la URL base que estés utilizando.
Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.