Corregir error de clave API no válida en Claude Code

Por qué Claude Code muestra un error de clave de API no válida

Claude Code falla con Invalid API key por dos motivos diferentes, y las soluciones son opuestas. Puede que pretendiera autenticarse con una clave de API y que esa clave sea incorrecta, se haya revocado o pertenezca a otra cuenta. O puede que nunca pretendiera usar una clave y que haya quedado una variable ANTHROPIC_API_KEY en el entorno del servidor, con prioridad sobre la suscripción con la que inició sesión. La documentación de Anthropic, a fecha de septiembre de 2026, es clara sobre el segundo caso: una clave definida en el entorno se utiliza en lugar de la suscripción Claude Pro, Max, Team o Enterprise, incluso cuando la sesión está iniciada.

Determine en qué caso se encuentra antes de cambiar nada. Inicie Claude Code y ejecute /status. La documentación describe una fila Login method que muestra la cuenta de la suscripción y una fila API key que aparece cuando se utiliza una clave de API. Si ve la fila de la clave de API en un equipo donde sólo ha ejecutado /login, el problema está en el entorno y volver a autenticarse no lo solucionará.

Todo lo que aparece a continuación son comandos que debe ejecutar en su propio servidor. Lea la salida antes de actuar.

El orden de las credenciales y por qué /login no ayuda

Cuando hay varias credenciales disponibles, Claude Code elige una según el orden documentado:

• Las credenciales del proveedor cloud, cuando CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX o CLAUDE_CODE_USE_FOUNDRY está definida.
• La variable ANTHROPIC_AUTH_TOKEN, enviada como cabecera Authorization: Bearer.
• La variable ANTHROPIC_API_KEY, enviada como cabecera X-Api-Key.
• La salida de un script apiKeyHelper.
• La variable CLAUDE_CODE_OAUTH_TOKEN, que contiene un token de claude setup-token.
• Las credenciales de perfil y federación de Anthropic.
• Las credenciales OAuth de suscripción que escribe /login.

Lea esa lista desde el final. /login escribe la credencial en la última posición, que en Linux termina en ~/.claude/.credentials.json con permisos 0600. Cualquier credencial de entorno situada por encima tiene prioridad. Por eso, un inicio de sesión nuevo actualiza una credencial que la sesión nunca utiliza: el inicio de sesión funciona, pero pierde la prioridad. Esa es la razón por la que la solución más evidente no produce ningún efecto.

Las sesiones interactivas añaden otro paso que suele causar confusión. La documentación indica que se le solicita una vez que apruebe o rechace una clave de API encontrada en el entorno, y que la elección se guarda. La aprobación que aceptó hace meses sigue vigente. Puede cambiarla con el interruptor "Usar una clave de API personalizada" en /config. Ese interruptor sólo aparece mientras ANTHROPIC_API_KEY esté definida en el entorno. En modo no interactivo, es decir, cuando claude -p se ejecuta dentro de un script o un trabajo de cron, no aparece ningún aviso: la clave siempre se utiliza cuando está presente.

¿Cómo localizo un ANTHROPIC_API_KEY residual en un VPS?

Primero, confirme que existe en el shell desde el que inicia Claude Code.

env | grep -i anthropic

Después, ejecute la corrección que ofrece la propia página de solución de problemas de Anthropic. También sirve como prueba:

unset ANTHROPIC_API_KEY
claude

Si Claude Code se inicia y /status muestra ahora su suscripción, habrá confirmado la causa. La variable vuelve a aparecer en el siguiente shell porque unset sólo modifica el shell en el que lo ejecutó. El resto de esta sección explica cómo localizar lo que la define.

Perfiles del shell y archivos de entorno de todo el sistema

grep -rn ANTHROPIC ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc \
  ~/.config/fish/config.fish /etc/environment /etc/profile /etc/profile.d/ 2>/dev/null

La página de Anthropic menciona ~/.zshrc, ~/.bashrc y ~/.profile. En un servidor, amplíe la búsqueda. /etc/environment lo lee PAM (módulos de autenticación conectables) al iniciar sesión para todos los usuarios del equipo. Así es como una clave definida por otro administrador puede acabar en su sesión. Los archivos de /etc/profile.d/ se ejecutan para los shells de inicio de sesión. Tenga en cuenta que .bashrc sólo se lee en shells interactivos, por lo que nunca puede explicar un fallo dentro de un servicio de systemd. El archivo relevante depende de cómo se inició Claude Code.

Unidades de systemd

Una unidad no lee su perfil del shell. Su entorno procede de las líneas Environment= y EnvironmentFile= de la unidad y de cualquier configuración adicional.

systemctl cat claude-agent.service
systemctl show -p Environment claude-agent.service

systemctl cat muestra el archivo de la unidad seguido de todas las configuraciones adicionales de /etc/systemd/system/claude-agent.service.d/. Es ahí donde suele ocultarse una sobrescritura. systemctl show -p Environment muestra lo que systemd pasará realmente al proceso. Para un servicio que se ejecuta con su propio usuario, añada --user a ambos comandos. Después de editar una unidad, ejecute sudo systemctl daemon-reload y reinicie el servicio. El entorno se construye cuando se inicia el proceso, y un proceso en ejecución conserva la copia que recibió.

Sesiones de tmux y screen que sobrevivieron a la edición

Este problema hace perder horas. Un servidor de tmux conserva el entorno con el que se inició, y los paneles nuevos lo heredan del servidor, no del shell actual. Elimina la exportación de .bashrc, abre un panel nuevo y la clave antigua sigue ahí.

tmux show-environment | grep -i ANTHROPIC
tmux set-environment -r ANTHROPIC_API_KEY

set-environment -r marca el nombre que se debe eliminar del entorno que tmux entrega a los procesos nuevos. Añadir -g hace lo mismo con el entorno global del servidor. Los paneles que ya están abiertos conservan su propia copia porque el entorno de un proceso sólo puede modificarse desde dentro de ese proceso. Después de eliminar la exportación, la opción fiable es desconectarse, ejecutar tmux kill-server e iniciar una sesión nueva. screen se comporta de la misma forma. Conviene saberlo antes de configurar una sesión de Claude Code de larga duración en tmux en un VPS, porque ese tipo de sesión puede sobrevivir a tres rondas de cambios de configuración.

Para leer el entorno de un proceso que ya se está ejecutando, solicítelo al kernel:

tr '\0' '\n' < /proc/$(pgrep -n claude)/environ | grep -i anthropic

Esto muestra los valores que recibió el proceso en el momento de ejecutar exec, es decir, los valores que realmente está usando. Debe ser el propietario del proceso o root para leer ese archivo, y pgrep -n claude selecciona la coincidencia más reciente. Compruebe el PID si hay varios procesos en ejecución.

Docker y Compose

docker exec claude-agent env | grep -i anthropic
docker compose config

El primer comando muestra el entorno dentro de un contenedor en ejecución, incluidos los valores procedentes de --env-file, de un bloque environment: o de una línea ENV integrada en la imagen. docker compose config muestra el archivo de Compose con las variables resueltas. Así verá el valor que se pasará, en lugar del marcador ${ANTHROPIC_API_KEY} que escribió. Ambos comandos muestran secretos en el terminal, así que ejecútelos en una sesión que pueda limpiar. Compose también carga automáticamente un archivo .env situado junto al archivo de Compose. Esta es la fuente habitual de una clave que nadie recuerda haber añadido.

El archivo de configuración que sobrevive a cualquier corrección del shell

Los archivos de configuración de Claude Code contienen un bloque env. La documentación es explícita sobre el conflicto: cuando la misma variable está definida tanto en el shell como en el bloque env de un archivo de configuración, se aplica el valor del archivo de configuración. Una clave escrita allí prevalece sobre cualquier unset que introduzca.

grep -rn ANTHROPIC ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

Compruebe tanto los archivos del proyecto como el archivo del usuario. .claude/settings.json normalmente se confirma en el repositorio, por lo que se comparte con todas las personas que lo clonen. Las organizaciones también pueden distribuir configuraciones administradas, que tienen prioridad sobre sus propios archivos. Si encuentra una clave que no puede eliminar, debe contactar con el administrador correspondiente.

La otra posibilidad: la clave realmente es incorrecta

Si /status muestra una clave de API y eso era lo previsto, tome el error literalmente. La referencia de errores de Anthropic indica estas causas para Invalid API key:

• La clave está mal formada o es incorrecta.
• La clave se revocó o caducó.
• La clave pertenece a otra organización o cuenta.

Inspeccione el valor sin imprimirlo en el historial de la terminal:

echo "len=${#ANTHROPIC_API_KEY} tail=${ANTHROPIC_API_KEY: -6}"

Una longitud de uno o dos caracteres más de lo previsto suele indicar que se copió un salto de línea final o una comilla, o que un $(cat keyfile) incluyó el salto de línea al final del archivo. El valor se envía en la cabecera X-Api-Key, por lo que un carácter adicional significa que la credencial enviada no es la clave que creó.

Compruebe también ANTHROPIC_AUTH_TOKEN en la misma salida, porque aparece antes que la clave de API. Un token bearer antiguo de una prueba con un proxy significa que la clave que está corrigiendo no es la credencial que se está enviando. También conviene revisar ANTHROPIC_BASE_URL en esa salida, porque un valor antiguo puede dirigir el cliente a una puerta de enlace que ya no existe. Para entender las cabeceras, cómo funciona la autenticación de claves de API de Anthropic explica qué contiene cada una. Antes de decidir qué credencial debe conservar esta máquina, la diferencia entre un inicio de sesión con suscripción y una clave de API ofrece el contexto necesario.

Hay algo que este error no indica: un problema de capacidad. Si la sesión se autentica y después las solicitudes fallan mientras está en uso, está ante el error de modelo sobrecargado, que no requiere cambiar ninguna credencial.

¿Por qué falla mi script apiKeyHelper?

apiKeyHelper es una clave de configuración que identifica un script que Claude Code ejecuta para obtener una credencial. Se usa para rotar tokens o para obtener tokens de corta duración, por ejemplo, una clave recuperada de un almacén seguro. El contrato es sencillo: el script debe imprimir la clave actual en la salida estándar y finalizar correctamente. La documentación indica que un script que finaliza con un error, agota el tiempo de espera o no imprime nada hace que las solicitudes fallen con Your apiKeyHelper script is failing en un plazo de tres intentos.

Ejecútelo manualmente y compruebe ambas partes del contrato:

out=$(/usr/local/bin/anthropic-key.sh)
echo "exit=$? len=${#out} tail=${out: -6}"

Una salida distinta de cero indica un fallo, aunque la clave se haya imprimido correctamente. Un helper que imprime Fetching credential... en la salida estándar antes de la clave también falla, porque esa línea pasa a formar parte de la credencial. Envíe los mensajes de progreso a la salida de error estándar.

Después, pruébelo del mismo modo que lo ejecutará un servicio:

env -i HOME="$HOME" PATH=/usr/bin:/bin /usr/local/bin/anthropic-key.sh
echo "exit=$?"

env -i inicia el script con un entorno casi vacío. Un helper que llama a aws, vault o gcloud desde un directorio que su .bashrc añade a PATH funciona durante las pruebas y falla al ejecutarse en producción, porque el proceso de Claude Code en ejecución nunca leyó su .bashrc. Asegúrese de que el script sea ejecutable y de que todo lo que invoque use una ruta absoluta, o establezca PATH dentro del propio script.

En un servidor también importan otros dos comportamientos documentados. De forma predeterminada, Claude Code vuelve a ejecutar el helper después de cinco minutos, y CLAUDE_CODE_API_KEY_HELPER_TTL_MS establece un intervalo diferente. Por tanto, una configuración que funciona al arrancar y falla una hora después está fallando durante la actualización, no durante el inicio. Si el helper tarda más de diez segundos en devolver una clave, Claude Code muestra un aviso en la barra de indicaciones con el tiempo transcurrido. Ese aviso indica una llamada lenta, no una llamada fallida. Es una alerta temprana antes de que el tiempo de espera se convierta en un error.

¿Realmente necesita la clave de API en este equipo?

La solución no siempre consiste en eliminarla. Mantenga la clave cuando el equipo deba facturar por separado:

• Un agente desatendido en una VPS facturada a Console no consume los límites de suscripción de una persona.
• Ejecuciones no interactivas, en las que claude -p no tiene un terminal para aprobar nada y la clave siempre se usa cuando está presente.
• Equipos que no tienen ninguna suscripción asociada.
• Un equipo compartido o de un cliente donde no se debe almacenar una sesión de suscripción personal.

El coste suele decidirlo, y la comparación de precios entre la API y las suscripciones es el lugar adecuado para resolverlo.

Elimine la clave cuando el equipo sea suyo y la suscripción sea la que ya paga. Después, haga que la eliminación sea permanente. En lugar de exportar la clave en ~/.bashrc, donde la hereda cada shell interactiva, entréguela sólo al servicio que la necesita:

[Service]
EnvironmentFile=/etc/claude-agent.env

Mantenga ese archivo con permisos 600 y como propietario al usuario con el que se ejecuta el servicio. Sus sesiones interactivas nunca la verán, por lo que su propio claude seguirá usando la suscripción mientras el servicio seguirá usando la clave. Si necesita una credencial de suscripción en un lugar sin navegador, claude setup-token muestra un token OAuth que puede pegar en CLAUDE_CODE_OAUTH_TOKEN. Conviene conocer sus limitaciones documentadas antes de depender de él: sólo puede realizar solicitudes a modelos, por lo que las sesiones de Remote Control y los conectores de claude.ai no están disponibles. Decidirlo una vez por equipo y escribirlo en el archivo de unidad evita el fallo que trata esta página, porque comienza con una clave que nadie recuerda haber configurado. Limitar lo que esa credencial puede alcanzar una vez configurada es otra tarea, que se trata en ejecutar Claude Code de forma segura en una VPS.

Una advertencia antes de usar la solución más drástica. /logout elimina las credenciales almacenadas, y la documentación indica que también borra las credenciales guardadas de servidores MCP (protocolo de contexto del modelo) y los secretos de los plugins. Por tanto, tendrá que volver a autorizar esos componentes.

FAQ

¿Por qué Claude Code indica que la clave de API no es válida si tengo una suscripción?

Porque una ANTHROPIC_API_KEY en el entorno tiene prioridad sobre el inicio de sesión de la suscripción. La documentación de Anthropic indica que una clave definida en el entorno se usa en lugar de la suscripción Pro, Max, Team o Enterprise, incluso si ha iniciado sesión. En modo no interactivo, con -p, la clave siempre se usa cuando está presente. Ejecute /status dentro de Claude Code para ver qué credencial seleccionó la sesión. Si aparece una fila API key y nunca la definió intencionadamente, ejecute unset ANTHROPIC_API_KEY y vuelva a iniciar claude para confirmar la causa.

¿Ejecutar /login corrige el error de clave de API no válida?

No mientras la variable esté definida. /login escribe las credenciales OAuth de la suscripción, que ocupan el último lugar en el orden de credenciales de Claude Code, por debajo de las variables de entorno y de apiKeyHelper. El inicio de sesión se completa, pero después se omite. Por eso repetirlo no cambia nada. Elimine la variable de todos los lugares donde esté definida o desactive el interruptor "Use custom API key" en /config. Según la documentación, esta opción aparece sólo cuando ANTHROPIC_API_KEY está definida en el entorno.

¿Cómo puedo ver qué método de autenticación usa Claude Code?

Ejecute /status en la sesión. La documentación describe una fila Login method que muestra la cuenta de la suscripción y una fila API key que aparece cuando se usa una clave de API. Compare ese resultado con env | grep -i anthropic en el mismo shell desde el que inició Claude Code. Si un servicio o contenedor ejecuta Claude Code, consulte el entorno del proceso con tr '\0' '\n' < /proc/<pid>/environ. Un proceso en ejecución conserva el entorno que recibió al iniciarse, no el del shell actual.

Mi script apiKeyHelper funciona cuando lo ejecuto. ¿Por qué Claude Code sigue fallando?

Normalmente, la causa está en el entorno o en el código de salida. Claude Code ejecuta el helper desde su propio proceso, que no ha leído el perfil de su shell. Por eso un helper que depende de una entrada PATH de .bashrc falla en ese contexto, aunque funcione en el terminal. Pruébelo con env -i HOME="$HOME" PATH=/usr/bin:/bin /path/to/helper y compruebe echo $? después. La documentación incluye como fallos los casos en que el script termina con un error, supera el tiempo de espera o no imprime nada. El resultado se muestra como Your apiKeyHelper script is failing. Todo lo que se escriba en la salida estándar, excepto la clave, pasa a formar parte de la credencial. Envíe los mensajes de progreso a la salida de error estándar.