Claude Code API Error 401 OAuth token has expired: 5 soluciones probadas

Respuesta corta: Claude Code API Error 401 OAuth token has expired significa que el token de inicio de sesión caducó, la renovación automática falló y la API rechazó la petición. El mensaje completo suele ser Please run /login · API Error: 401 OAuth token has expired. Please obtain a new token or refresh your existing token. Escribe /login en la sesión y vuelve a iniciar sesión; con eso se arregla la mayoría de los casos. Si tú mismo definiste CLAUDE_CODE_OAUTH_TOKEN (CI, scripts, Docker), /login no basta, porque las sesiones nuevas siguen leyendo el valor viejo: genera otro token con claude setup-token y reemplázalo. Reprodujimos el error en Claude Code 2.1.312 con una API simulada y un token caducado; abajo está la salida. El texto del error y las soluciones siguen la referencia oficial de errores de Claude Code, revisada el 29 de octubre de 2026.

Qué significa Claude Code API Error 401 OAuth token has expired

La documentación agrupa dos mensajes:

• OAuth token revoked · Please run /login: el token fue revocado, por ejemplo porque cerraste sesión en todos los dispositivos o un administrador te quitó el acceso.
• Please run /login · API Error: 401 OAuth token has expired ...: el token caducó y la renovación automática falló a mitad de sesión.

En los dos casos Claude Code sí envió la petición y la API la rechazó. En modo -p y en el Agent SDK aparece como Failed to authenticate. API Error: 401 OAuth token has expired ..., con el código estructurado authentication_failed.

Hay tres mensajes parecidos que significan otra cosa:

• Login expired · Please run /login: Claude Code ya no pudo renovar el inicio de sesión guardado y lo borró, así que ni siquiera envía la petición.
• API Error: 401 Invalid authentication credentials: el token no caducó; la cuenta, la organización o la API key ya no se aceptan.
• Not logged in · Please run /login: no encontró ninguna credencial.

Nuestra prueba: un token caducado en cada petición

Un token real de suscripción no se puede hacer caducar a voluntad, así que apuntamos Claude Code 2.1.312 a un servidor local simulado con ANTHROPIC_BASE_URL. El servidor responde a todo con un 401 y el cuerpo {"type":"authentication_error","message":"OAuth token has expired. Please obtain a new token or refresh your existing token."}, el mismo texto que copian los usuarios en GitHub. Pusimos en CLAUDE_CODE_OAUTH_TOKEN un valor falso sk-ant-oat01-....

• claude -p hi mostró Failed to authenticate. API Error: 401 OAuth token has expired. Please obtain a new token or refresh your existing token. Con --output-format json el resultado traía "is_error": true y "api_error_status": 401.
• El servidor registró 4 peticiones, todas con Authorization: Bearer sk-ant-oat01-.... Claude Code siguió enviando el valor de la variable, tal como dice la documentación.
• claude auth status seguía diciendo "loggedIn": true, "authMethod": "oauth_token". Ese comando solo indica qué credencial está configurada; no comprueba si el token todavía funciona.
• Tras unset CLAUDE_CODE_OAUTH_TOKEN, sin inicio de sesión guardado, salió Not logged in · Please run /login. Con una API key apuntando a un servidor simulado que responde bien, el mismo prompt devolvió respuesta.

Como comparación, un token mal formado enviado a la API real devolvió API Error: 401 OAuth access token is invalid.: «invalid» indica que el token no se reconoce, «expired» que caducó.

Cómo solucionar Claude Code API Error 401 OAuth token has expired

• Mira qué credencial está activa. Ejecuta /status. Un token que definiste tú aparece en una fila Auth token con el valor CLAUDE_CODE_OAUTH_TOKEN.
• Inicio de sesión guardado: escribe /login en la sesión y entra de nuevo.
• -p o Agent SDK con inicio de sesión guardado: ejecuta claude en el mismo entorno, completa /login y vuelve a lanzar tu comando.
• CLAUDE_CODE_OAUTH_TOKEN: ejecuta claude setup-token en un equipo con navegador, copia el token que imprime y reemplaza el valor viejo:

export CLAUDE_CODE_OAUTH_TOKEN=tu-token-nuevo

Según la documentación, setup-token crea un token válido por un año y no lo guarda en ningún sitio. Si el valor viejo está en el perfil de tu shell o en el bloque env de un archivo settings.json, cámbialo ahí también o las sesiones nuevas lo seguirán leyendo. Antes de la v2.1.225, Claude Code podía cambiar el valor de la variable por un token guardado de corta duración a mitad de sesión, que volvía a caducar; si tienes una versión anterior, actualiza.

• Automatización sin navegador: usa ANTHROPIC_API_KEY o un token de setup-token.
• Te pide iniciar sesión cada vez que arrancas: revisa que la hora del sistema sea correcta, porque la validación del token depende de ella. En macOS, ejecuta claude doctor y sigue los pasos del llavero en la guía oficial de problemas de inicio de sesión.

Elige la solución según cómo inicias sesión

Desde la v2.1.210, si un inicio de sesión guardado no se puede renovar, /status muestra una fila Login con Expired — log in again. La documentación de autenticación añade que, cuando faltan 3 días, Claude Code avisa al arrancar con Your login expires in 3 days · run /login to renew. Si vas a dejar una tarea larga corriendo sola, renueva en ese momento. Si aún no tienes la CLI, empieza por nuestra guía para instalar Claude Code.

Si /login no lo arregla: casos en GitHub

Estos reportes son de versiones anteriores y ya están cerrados, pero muestran lo que le pasó a la gente:

• Issue #15007: tras un 401 en una sesión activa, /login terminaba bien en el navegador pero la sesión seguía fallando. Un usuario de Windows comentó que cerrar Claude y abrirlo de nuevo lo resolvió.
• Issue #44729: /login abría el navegador pero fallaba con OAuth error: timeout of 15000ms exceeded.
• Issue #33291: en la extensión de VS Code, durante un incidente publicado en la página de estado, el autor lo arregló ejecutando claude auth login en una terminal.

Así que, si /login sale bien y el siguiente prompt sigue fallando, cierra Claude Code, vuelve a abrirlo (con claude --continue recuperas la conversación) y prueba otra vez. Si el inicio de sesión en el navegador falla en WSL2, SSH o contenedores, consulta los pasos oficiales. Más errores en nuestra guía de errores de Claude Code.

Preguntas frecuentes

¿Claude Code API Error 401 OAuth token has expired significa que se acabó mi suscripción?

No. Es un problema del token de inicio de sesión. Si te quitan el acceso verás OAuth token revoked; si la cuenta u organización está desactivada, Invalid authentication credentials.

¿Por qué claude auth status dice que tengo sesión iniciada?

Porque informa qué credencial está configurada, no si la API la acepta. En nuestra prueba mostró loggedIn: true con un token caducado.

¿Cuánto dura un token de setup-token?

Un año, según la documentación.

¿Sirve usar una API key?

Sí, si te parece bien pagar tarifas de API. ANTHROPIC_API_KEY tiene prioridad sobre el inicio de sesión de la suscripción (en modo interactivo Claude Code pregunta una vez si quieres usarla). Para ver cómo funcionan los límites de la suscripción, lee nuestra guía de la cuota de Claude Pro y Max.