Solucionar error de clave API invalida 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 dos soluciones son opuestas. Puede que quisiera autenticarse con una clave de API y que esa clave sea incorrecta, esté revocada o pertenezca a otra cuenta. O puede que nunca quisiera usar una clave y que un ANTHROPIC_API_KEY residual en el entorno del servidor tenga prioridad sobre la suscripción con la que inició sesión. La documentación de Anthropic, a fecha de octubre de 2026, es clara sobre el segundo caso: cuando aprueba una clave definida en el entorno, esta se usa en lugar de su suscripción Claude Pro, Max, Team o Enterprise aunque haya iniciado sesión, y con claude -p la clave siempre se usa cuando está presente.

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 su suscripción y una fila API key que aparece cuando se usa una clave de API. Si ve la fila de clave de API en un equipo donde sólo ha ejecutado /login, compruebe el entorno, la configuración y apiKeyHelper; volver a autenticarse no eliminará esas credenciales.

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

Orden de credenciales y por qué /login no ayuda

Cuando hay varias credenciales disponibles, Claude Code elige una siguiendo un 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.
• Los perfiles de Anthropic seleccionados explícitamente mediante ANTHROPIC_PROFILE, las credenciales de federación seleccionadas mediante variables de entorno y los perfiles activos o predeterminados que usan la autenticación oidc_federation.
• Las credenciales OAuth de la suscripción que escribe /login.
• Un perfil de Anthropic activo o predeterminado que usa la autenticación user_oauth, salvo que ANTHROPIC_PROFILE lo seleccione explícitamente.

Lea esa lista desde el final. /login escribe las credenciales OAuth de la suscripción, que en Linux se almacenan en ~/.claude/.credentials.json con permisos de archivo 0600. Estas tienen prioridad sobre un perfil user_oauth activo o predeterminado, salvo que ANTHROPIC_PROFILE lo seleccione explícitamente, pero están por debajo de las credenciales de entorno y apiKeyHelper. Una API key aprobada en el entorno sigue teniendo prioridad sobre el inicio de sesión de la suscripción. 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 de que la solución obvia no haga nada. Con CLAUDE_CODE_OAUTH_TOKEN, /login cambia la sesión actual al nuevo inicio de sesión, pero las sesiones nuevas vuelven a leer la variable hasta que la elimine. Una sesión iniciada en una pasarela de Claude apps queda fuera de este orden y usa su token de pasarela en lugar de estas credenciales, incluso cuando hay definida una variable de proveedor cloud.

Las sesiones interactivas añaden otro paso que suele causar confusión. La documentación indica que se solicita una sola vez aprobar o rechazar una API key encontrada en el entorno, y que la elección se guarda. Si la aprobó hace meses, esa aprobación sigue vigente y la key continúa teniendo prioridad sobre su inicio de sesión. Si la rechazó, la key se ignora sin volver a preguntar. Esto produce el problema contrario: la variable está definida, env la muestra y la sesión nunca la utiliza. Puede cambiar la elección con el interruptor "Use custom API key" de /config. Ese interruptor sólo aparece mientras ANTHROPIC_API_KEY está definida en el entorno. En modo no interactivo, es decir, claude -p dentro de un script o un cron job, no se muestra ningún aviso: la key siempre se utiliza cuando está presente.

¿Cómo encuentro la variable ANTHROPIC_API_KEY perdida 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 indica la propia página de solución de problemas de Anthropic, que también sirve como prueba:

unset ANTHROPIC_API_KEY
claude

Si Claude Code se inicia y /status ahora muestra su suscripción, ha confirmado la causa. La variable volverá a aparecer en el siguiente shell si un archivo de inicio todavía la define, porque unset sólo cambia el shell en el que lo ejecutó. El resto de esta sección trata de encontrar qué la define.

Perfiles de 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. El módulo pam_env lee /etc/environment cuando está habilitado en la configuración PAM (módulos de autenticación conectables) del inicio de sesión. Así es como una clave de todo el sistema termina en su sesión. Los archivos de /etc/profile.d/ se ejecutan cuando el perfil del shell de inicio de sesión los carga. Un servicio de systemd no lee .bashrc automáticamente; compruebe si su comando inicia explícitamente un shell o carga un perfil. El archivo relevante depende de cómo se inició Claude Code.

Unidades de systemd

Una unidad no lee el perfil de su shell. Su entorno incluye las líneas Environment= y EnvironmentFile= de la unidad y de cualquier drop-in, además de las variables proporcionadas por el gestor de servicios.

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

systemctl cat muestra el archivo de unidad seguido de sus drop-ins, incluidas las anulaciones de /etc/systemd/system/claude-agent.service.d/. systemctl show -p Environment muestra las asignaciones Environment= de la unidad; revise también cualquier archivo EnvironmentFile=, porque su contenido se lee por separado cuando se inicia el 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, porque el entorno se ensambla cuando se inicia el proceso y un proceso en ejecución conserva la copia que recibió.

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

Este problema puede hacerle perder horas. Un servidor de tmux conserva el entorno con el que se inició, y los paneles nuevos heredan los entornos global y de sesión combinados. Elimina la exportación de .bashrc, abre un panel nuevo y la clave antigua sigue allí.

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, y añadir -g hace lo mismo para el entorno global del servidor. Los paneles que ya están abiertos conservan su propia copia, porque el entorno de un proceso sólo se puede cambiar desde dentro de ese proceso. Después de eliminar la exportación, la medida fiable es desconectarse, ejecutar tmux kill-server e iniciar una sesión nueva. 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 ediciones de configuración.

Para leer el entorno de un proceso que ya está en ejecución, pídaselo 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 exec; no refleja cambios posteriores, como los valores que Claude Code carga desde la configuración. Debe ser el propietario del proceso o root para leer ese archivo, y pgrep -n claude selecciona la coincidencia más reciente, así que 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, incluido todo lo procedente de --env-file, un bloque environment: o una línea ENV incorporada en la imagen. docker compose config muestra el archivo de Compose con las variables resueltas, de modo que puede 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 esté dispuesto a limpiar. Compose también carga de forma predeterminada un archivo .env del directorio del proyecto para la interpolación; un valor de ese archivo llega al contenedor cuando la configuración de Compose lo transmite.

El archivo de configuración que sobrevive a todas las correcciones del shell

Los archivos de configuración de Claude Code contienen un bloque env, y la documentación es explícita sobre el conflicto: cuando la misma variable está definida tanto en el shell como en un bloque env de un archivo de configuración, el valor del archivo de configuración se aplica en la mayoría de las sesiones. Las excepciones son las sesiones iniciadas por la aplicación Claude Desktop o por un entorno de ejecución autohospedado, donde prevalece el entorno de inicio. Para claude iniciado en un terminal del servidor, una clave escrita allí prevalece sobre cualquier unset que escriba.

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

Revise los archivos del proyecto además del archivo del usuario. Normalmente .claude/settings.json se incluye en el control de versiones, por lo que se comparte con todas las personas que clonan el repositorio. Las organizaciones también pueden distribuir configuraciones administradas, que tienen prioridad sobre sus propios archivos. Si encuentra una clave que no puede eliminar, debe consultar a esa organización.

La otra posibilidad: la clave realmente es incorrecta

Si /status muestra una clave de API y eso era lo esperado, tome el error al pie de la letra. La referencia de errores de Anthropic indica que Invalid API key · Fix external API key significa que la API rechazó la clave procedente de ANTHROPIC_API_KEY o de un script apiKeyHelper, o que Claude Code bloqueó la clave antes de enviarla. Estas son sus comprobaciones para este error:

• Busque errores tipográficos en la clave.
• Confirme en la Console que la clave no se haya revocado.
• Asegúrese de que una herramienta como direnv, un complemento dotenv para el shell o el terminal de un IDE no haya cargado una clave obsoleta desde un archivo .env del proyecto.

Inspeccione el valor sin imprimirlo en el historial del terminal:

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

Una longitud de uno o dos caracteres más de lo esperado suele indicar que se copió un salto de línea o una comilla, o que un archivo de claves guardado con finales de línea de Windows dejó un retorno de carro. Leer el archivo con $(cat keyfile) no conserva un salto de línea final simple, porque Bash elimina los saltos de línea finales de la salida de la sustitución de comandos. No elimina el retorno de carro situado delante de ese salto de línea, por lo que un archivo con finales de línea de Windows sigue dejando un carácter adicional en la variable. Las versiones actuales detectan los caracteres que una cabecera no puede transportar antes de enviar la solicitud: cuando el mensaje continúa después de Fix external API key con una descripción como Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break, Claude Code detiene la solicitud y la API nunca recibe la clave. La misma comprobación detecta una comilla curva, pero una comilla recta es un carácter válido en una cabecera, por lo que se envía como parte de la cabecera X-Api-Key y la credencial enviada no es la clave que creó.

Compruebe ANTHROPIC_AUTH_TOKEN en la misma salida, porque aparece antes que la clave de API. Un token bearer olvidado 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, ya que un valor antiguo dirige el cliente a una puerta de enlace que quizá ya no exista. Para conocer el funcionamiento de 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, consulte la diferencia entre iniciar sesión con una suscripción y usar una clave de API.

Una cosa que este error no indica es un problema de capacidad. Si las solicitudes fallan con 529 Overloaded, está viendo 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 tokens de corta duración, como una clave obtenida de un vault. El contrato es simple: 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 peticiones fallen con Your apiKeyHelper script is failing en un máximo de tres intentos.

Ejecútelo manualmente y compruebe las dos partes de ese contrato:

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

Un código de salida distinto de cero indica un fallo aunque la clave se haya impreso correctamente. Un helper que imprime Fetching credential... en la salida estándar antes de la clave también falla: desde v2.1.227, Claude Code rechaza cualquier salida que contenga algo distinto de la clave e informa de que el helper returned output that cannot be used as an API key, mientras que las versiones anteriores enviaban esa línea como parte de la credencial. Envíe los mensajes de progreso a la salida de error estándar. Dentro de una sesión, /status muestra una fila apiKeyHelper con el texto Failing, el último código de salida y la salida de error.

Después, pruébelo de la forma en 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 en un servicio cuyo entorno de inicio no incluye ese directorio. 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 eso, una configuración que funciona al inicio y falla una hora después está fallando durante una 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 solicitudes con el tiempo transcurrido. Ese aviso indica una llamada lenta, no un fallo, y sirve como advertencia temprana antes de que el tiempo de espera se convierta en un error.

¿Realmente necesita la API key en este equipo?

La solución no siempre es eliminarla. Conserve la clave cuando la máquina tenga motivos para facturarse por separado:

• Un agente desatendido en un VPS facturado a la consola no consume los límites de la suscripción de un usuario.
• Ejecuciones no interactivas, donde claude -p no dispone de terminal para aprobar nada y la clave se utiliza siempre que está presente.
• Máquinas sin una suscripción asociada.
• Un equipo compartido o de un cliente donde no debe almacenarse el inicio de sesión de una suscripción personal.

El coste suele ser el factor decisivo, y la comparativa de precios de la API y la suscripción es donde debe realizar los cálculos.

Elimine la clave cuando el equipo sea suyo y la suscripción sea la que usted ya paga. Después, asegúrese de que la eliminación sea permanente. En lugar de exportar la clave en ~/.bashrc, donde cada shell interactiva la hereda, asígnela únicamente al servicio que la necesite:

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

Mantenga ese archivo con permisos 600, propiedad del usuario que ejecuta el servicio. Sus sesiones interactivas nunca lo verán, por lo que su propio claude seguirá utilizando la suscripción mientras el servicio utiliza la clave. Si necesita una credencial de suscripción en un entorno sin navegador, claude setup-token genera un token OAuth para pegar en CLAUDE_CODE_OAUTH_TOKEN. Conviene conocer sus límites documentados antes de depender de él: solo puede realizar peticiones de modelos, por lo que las sesiones de Remote Control y los conectores de claude.ai no están disponibles con esta opción. Decidir esto una vez por máquina y definirlo en el archivo de unidad es lo que evita el fallo que trata esta página, ya que este suele originarse por una clave que nadie recuerda haber configurado. Limitar el alcance de esa credencial una vez implementada es una tarea distinta, descrita en ejecutar Claude Code de forma segura en un VPS.

Una advertencia antes de recurrir a medidas drásticas. /logout elimina las credenciales almacenadas, y la documentación indica que también borra los inicios de sesión de servidores MCP (model context protocol) y los secretos de los plugins guardados, por lo que deberá volver a autorizarlos posteriormente.

FAQ

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

Porque una ANTHROPIC_API_KEY definida en el entorno tiene prioridad sobre el inicio de sesión de la suscripción una vez aprobada. La documentación de Anthropic indica que una clave aprobada definida en el entorno se usa en lugar de la suscripción Pro, Max, Team o Enterprise, incluso si ha iniciado sesión, y que 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 configuró intencionadamente, ejecute unset ANTHROPIC_API_KEY y vuelva a iniciar claude para confirmar la causa.

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

No mientras se siga usando la API key aprobada del entorno. /login escribe las credenciales OAuth de la suscripción por debajo de las credenciales del entorno y de apiKeyHelper, pero por encima de un perfil user_oauth activo o predeterminado, salvo que ANTHROPIC_PROFILE lo seleccione explícitamente. El inicio de sesión se completa, pero después se ignora. Por eso repetirlo no cambia nada. Elimine la variable de donde esté definida o desactive el conmutador "Use custom API key" en /config. La documentación indica que este conmutador sólo aparece mientras ANTHROPIC_API_KEY esté definido 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 API key. Compare ese resultado con env | grep -i anthropic en el mismo shell desde el que inició la sesión. Si un servicio o un contenedor ejecuta Claude Code, inspeccione su entorno de inicio con tr '\0' '\n' < /proc/<pid>/environ. Ese archivo muestra los valores suministrados en el momento de la ejecución, por lo que también debe revisar los archivos de configuración en busca de valores que Claude Code cargue después.

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 con su propio entorno de proceso. Por tanto, un servicio al que le falte una entrada PATH de su terminal no encuentra un comando que sí funciona cuando lo prueba allí. Pruébelo con env -i HOME="$HOME" PATH=/usr/bin:/bin /path/to/helper y compruebe echo $? después. El fallo documentado incluye un script que termina con un error, agota el tiempo de espera, no muestra nada o muestra algo distinto de la clave, y se presenta como Your apiKeyHelper script is failing. Desde v2.1.227, una cabecera o una línea de registro en la salida estándar hace que el helper falle directamente. Envíe los mensajes de progreso a la salida de error estándar.