Error 401 authentication_error / invalid x-api-key: qué comprobar y en qué orden

Casi todos los errores 401 tienen una de cuatro causas, y solo una de ellas es «la clave es incorrecta». Las otras tres dejan la clave perfectamente válida; por eso recrearla suele ser un esfuerzo desperdiciado.

El error

resposta (HTTP 401)

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

Causas y soluciones de un vistazo

Causa	Solución
Encabezado incorrecto para el host	Anthropic lee x-api-key; la mayoría de las pasarelas compatibles con OpenAI leen Authorization: Bearer. El mismo valor colocado en el encabezado incorrecto llega como ausente.
Queda una variable de entorno antigua	Una ANTHROPIC_API_KEY olvidada en el perfil del shell puede prevalecer sobre la que acabas de exportar.
Se cambió la base URL sin cambiar la credencial	Apuntar a otro host no hace que allí sea válida la clave del proveedor anterior. El host y la credencial cambian juntos.
Espacios, saltos de línea o comillas en la clave	Copiar desde un PDF o un chat suele incluir caracteres invisibles. Comprueba la longitud de la cadena.

Comprueba qué contiene realmente el entorno

Antes de cambiar nada, observa las variables en el mismo shell que ejecuta la aplicación. En un número sorprendente de casos hay dos credenciales definidas a la vez, de proveedores diferentes.

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

Prueba la credencial fuera de la aplicación

Una solicitud directa permite distinguir entre «el host rechaza la clave» y «la aplicación no envía la clave». Si curl funciona y el código no, el problema no es la credencial.

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

Distingue 401 de 403 y 402

401 significa «no sé quién eres»: la credencial no fue aceptada. 403 significa «sé quién eres y no puedes»: estás autenticado, pero no tienes permiso. 402 significa «sé quién eres, pero falta saldo». Solo el 401 se resuelve modificando la credencial.

Si llamas a través de Kunavo

Kunavo lee la clave sk-kn- tanto en Authorization: Bearer como en x-api-key, y la base URL es el origen del sitio sin ninguna ruta posterior. Con Claude Code, usa ANTHROPIC_AUTH_TOKEN junto con ANTHROPIC_BASE_URL, porque el token no depende de la aprobación única que exige ANTHROPIC_API_KEY, y elimina explícitamente ANTHROPIC_API_KEY: un valor antiguo en esa variable es la causa más común de una sesión que parece configurada pero sigue rechazando la solicitud. El procedimiento paso a paso de autenticación está en la documentación de autenticación.

Preguntas frecuentes

¿Soluciona algo recrear la clave?

Solo si la clave fue realmente revocada. En las otras tres causas más comunes —encabezado incorrecto, variable antigua y base URL cambiada— la clave nueva falla exactamente igual.

¿Un 401 puede deberse a falta de saldo?

No. El saldo insuficiente es un 402, con un mensaje que habla de créditos. El 401 siempre se refiere a la identidad.

Funciona con curl y falla en mi código. ¿Por qué?

Casi siempre porque el código lee otra variable de entorno o se ejecuta en otro shell o contenedor donde no llegó el export. Imprime la credencial enmascarada dentro del proceso para confirmarlo.

Guías relacionadas

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.