EN · Read in English Explorar gratis

Receta · Básico · 5 min

Errores de Claude Code: 529, 401, 403, límites y cómo arreglarlos

El mensaje exacto, la causa y el arreglo de los errores más comunes de Claude Code: 529 Overloaded, 401, 403, límite de uso, contexto lleno, PATH y MCP.

Probado con Claude Code 2.1.316 · revisado

El problema

Estás en mitad de una tarea y Claude Code se detiene con un mensaje en inglés: API Error: Repeated 529 Overloaded errors, Not logged in · Please run /login, Context limit reached... Cada uno tiene una causa distinta y un arreglo distinto, y reintentar a ciegas no siempre sirve. Esta página reúne los errores más frecuentes con el mensaje literal (para que lo encuentres con Ctrl+F), qué lo provoca y qué hacer, paso a paso.

Los mensajes marcados como Reproducido con 2.1.316 los provocamos en Linux con una carpeta personal temporal (sin tocar la configuración real). El resto se copió tal cual de la referencia de errores oficial y de la guía de instalación e inicio de sesión.

La solución

1. Antes de nada: mira qué credencial y qué estado tienes

Tres comandos resuelven la mitad de los casos porque te dicen dónde está el fallo:

# Desde tu terminal, si claude ni siquiera arranca bien
claude doctor

Y dentro de una sesión:

/status    # qué cuenta, qué organización y qué credencial está activa
/doctor    # revisa instalación, ajustes, extensiones y uso de contexto
/mcp       # estado de cada servidor MCP

Si el error es del servidor (500, 529), consulta también status.claude.com antes de cambiar nada en tu equipo.

2. API Error: Repeated 529 Overloaded errors

Mensaje exacto (documentación oficial):

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Causa: la API está al límite de capacidad para todos los usuarios. Claude Code ya reintentó varias veces antes de mostrarte el mensaje. No es tu límite de uso y no descuenta de tu cuota.

Arreglo:

  1. Revisa status.claude.com por si hay un incidente de capacidad.
  2. Espera unos minutos y vuelve a intentarlo. Tu mensaje sigue en la conversación: basta con escribir try again o «inténtalo otra vez».
  3. Si tienes prisa, cambia de modelo con /model: la capacidad se mide por modelo. Claude Code a veces te lo propone él mismo con un aviso como Opus is experiencing high load, please use /model to switch to Sonnet.

El primo cercano es API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. Un 5xx de la API es un fallo interno del servicio, no de tu prompt ni de tu cuenta: mismo arreglo (estado, esperar, reintentar). Si persiste sin incidente publicado, usa /feedback.

3. Límite de uso alcanzado: You've hit your session limit

Mensajes exactos (documentación oficial):

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

Causa: los planes de suscripción tienen una cuota que se renueva. Se agotó la de la sesión, la semanal o la de una familia de modelos.

Arreglo:

  1. Ejecuta /usage para ver tus límites y cuándo se renuevan.
  2. Si el aviso es de Opus o Sonnet, cambia con /model a un modelo de otra familia y sigue trabajando. Si es el límite de sesión o semanal, cambiar de modelo no sirve: son límites compartidos por todos los modelos.
  3. Espera a la hora que indica el mensaje. En una sesión interactiva con suscripción de claude.ai, Claude Code puede esperar y continuar solo la tarea cuando se renueve el límite (opción Continue automatically at usage limit en /config).
  4. Si necesitas más, /usage-credits compra uso adicional en Pro, Max y Ultra, o lo solicita a tu administrador en Team y Enterprise.

Dos errores parecidos que no son tu cuota del plan:

4. Errores 401 y de inicio de sesión

Reproducido con 2.1.316 (sin ninguna credencial):

$ claude -p "hola"
Not logged in · Please run /login

Reproducido con 2.1.316 (con una clave inventada en ANTHROPIC_API_KEY):

$ ANTHROPIC_API_KEY=sk-ant-api03-claveinventada claude -p "hola"
Invalid API key · Fix external API key

Otros mensajes de la misma familia (documentación oficial):

OAuth token revoked · Please run /login
Please run /login · API Error: 401 OAuth token has expired ...
Please run /login · API Error: 401 Invalid authentication credentials
Login expired · Please run /login

Causa: Claude Code no puede demostrar quién eres. O no hay credencial, o la clave es incorrecta o está revocada, o tu sesión de claude.ai caducó y no se pudo renovar. El 401 Invalid authentication credentials indica que la API reconoció la credencial pero rechazó la cuenta u organización que hay detrás (revocada, desactivada o sin acceso).

Arreglo:

  1. Ejecuta /status para ver qué credencial está activa.
  2. Si usas tu suscripción, ejecuta /login. Si el fallo persiste, haz un reinicio limpio: /logout, cierra Claude Code, ábrelo con claude y vuelve a iniciar sesión.
  3. Si aparece Invalid API key, busca claves olvidadas en tu entorno. direnv, plugins de .env y las terminales de los editores pueden cargar una clave vieja sin que te des cuenta:
env | grep ANTHROPIC
  1. Si no quieres usar esa clave, quítala y entra con tu suscripción. Una ANTHROPIC_API_KEY aprobada tiene prioridad sobre tu sesión, así que /login sola no la reemplaza:
unset ANTHROPIC_API_KEY
claude
  1. Si te pide iniciar sesión una y otra vez, comprueba que el reloj del sistema esté en hora: la validación del token depende de ello.
  2. En automatización (CI, -p) donde no puedes iniciar sesión de forma interactiva, usa ANTHROPIC_API_KEY o genera un token de larga duración con claude setup-token.

5. API Error: 403 Request not allowed

Mensaje exacto (documentación oficial): API Error: 403 Request not allowed, justo después de iniciar sesión.

Causa: la cuenta inició sesión pero no tiene permiso para usar Claude Code, o un proxy corporativo interfiere.

Arreglo:

  1. Pro, Max o Ultra: confirma que tu suscripción está activa en claude.ai/settings.
  2. Cuenta de Console: tu usuario necesita el rol «Claude Code» o «Developer». Lo asigna un administrador en platform.claude.com/settings/members.
  3. Detrás de un proxy: revisa la configuración de red.

Si el 403 aparece al instalar (curl: (22) The requested URL returned error: 403), suele ser un proxy o filtro de red que bloquea la descarga, o que Claude Code no está disponible en tu país.

6. Contexto lleno: Context limit reached y errores al compactar

Mensajes exactos (documentación oficial):

Context limit reached · /compact or /clear to continue
Prompt is too long
Prompt is too long · automatic compaction failed: <the underlying error>
Autocompact is thrashing: the context refilled to the limit...

Causa: la conversación más los archivos adjuntos superan la ventana de contexto del modelo. Normalmente la compactación automática lo evita; si está desactivada o falla, aparece este error.

Arreglo:

  1. Ejecuta /compact para resumir lo anterior y liberar espacio, o /clear para empezar de cero.
  2. Ejecuta /context para ver qué ocupa la ventana: prompt del sistema, herramientas, archivos de memoria y mensajes.
  3. Desactiva los servidores MCP que no estés usando, porque sus definiciones de herramientas ocupan contexto en cada petición:
/mcp disable <nombre>
  1. Recorta los CLAUDE.md grandes o pasa instrucciones a reglas por ruta que solo se cargan cuando hacen falta.
  2. Si /compact responde Not enough messages to compact., la conversación tiene un solo intercambio y no hay nada que resumir: haz /clear y vuelve a enviar con menos texto pegado o archivos más pequeños.
  3. Si ves automatic compaction failed: ..., arregla primero el error que se nombra después de los dos puntos (por ejemplo, uno de autenticación); /compact fallará igual hasta entonces.
  4. Si ves Autocompact is thrashing, un archivo o la salida de una herramienta vuelve a llenar el contexto justo después de compactar. Pide a Claude que lea ese archivo por partes (un rango de líneas o una función), compacta con un enfoque concreto (/compact keep only the plan and the diff) o pasa ese trabajo a un subagente.
  5. Si desactivaste la compactación automática en /config, vuelve a activarla.

7. claude: command not found después de instalar

Reproducido con 2.1.316 (con un PATH sin ~/.local/bin):

bash: claude: command not found

Según tu sistema, el mensaje cambia (documentación oficial):

SistemaMensaje
macOSzsh: command not found: claude
Linuxbash: claude: command not found
Windows CMD'claude' is not recognized as an internal or external command
PowerShellclaude : The term 'claude' is not recognized as the name of a cmdlet

Causa: la instalación terminó, pero la carpeta donde quedó el programa (~/.local/bin en macOS y Linux, %USERPROFILE%\.local\bin en Windows) no está en tu PATH. El instalador lo avisa en Setup notes: pero no cambia el PATH por ti.

Arreglo en Linux y macOS:

  1. Comprueba que el programa existe:
ls -la ~/.local/bin/claude
  1. Comprueba si la carpeta está en el PATH (si no imprime nada, no está):
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
  1. Añádela. Para Bash en Linux:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Para Zsh (por defecto en macOS), cambia ~/.bashrc por ~/.zshrc. Para Bash en macOS, usa ~/.bash_profile.

  1. Verifica:
claude --version

Arreglo en Windows (PowerShell):

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Cierra y vuelve a abrir la terminal. Si usas la terminal de un editor (VS Code, Cursor), cierra y abre el editor entero: hereda el PATH del editor. Ojo: la extensión de VS Code trae su propia copia de Claude Code y no instala claude en el PATH; para usarlo en la terminal necesitas la instalación normal.

8. Permisos y sandbox: comandos denegados o bloqueados

En claude -p y el Agent SDK. Desde la versión 2.1.302, una ejecución con -p sin modo de permisos arranca en modo Manual (default): todo lo que necesita aprobación se deniega, porque no hay nadie que responda. Arreglo, elige uno:

# Permitir solo lo que necesita
claude -p "Ejecuta los tests y arregla los fallos" --allowedTools "Bash(npm test)"

# O dejar que el clasificador del modo auto revise cada acción
claude -p "Ejecuta los tests y arregla los fallos" --permission-mode auto

Con el sandbox activado en Linux o WSL2. El sandbox necesita bubblewrap y socat. Si falta alguno, la pestaña Dependencies de /sandbox lo indica. En Ubuntu o Debian:

sudo apt-get install bubblewrap socat

Reinicia Claude Code después de instalarlos: la comprobación se hace al arrancar. En Ubuntu 24.04 o posterior, si sysctl kernel.apparmor_restrict_unprivileged_userns devuelve 1, AppArmor impide que bubblewrap funcione; la guía de sandbox trae el perfil exacto que debes añadir.

Si exigiste el sandbox (sandbox.failIfUnavailable) y no se pudo iniciar, cada comando se rechaza con Sandbox is required but failed to initialize: <reason>. Arregla lo que dice el motivo y reinicia.

Otros fallos conocidos dentro del sandbox: docker es incompatible (sácalo con un patrón en excludedCommands, como docker compose *) y jest se cuelga por watchman (usa jest --no-watchman).

9. Un servidor MCP no conecta

Reproducido con 2.1.316 (un servidor stdio con un comando que no existe y uno HTTP en un puerto cerrado):

$ claude mcp list
Checking MCP server health…

fantasma: /ruta/que/no/existe/servidor  - ✘ Failed to connect — ENOENT: no such file or directory, posix_spawn '/ruta/que/no/existe/servidor'
remoto: http://127.0.0.1:9/mcp (HTTP) - ✘ Failed to connect — ECONNREFUSED: Unable to connect. Is the computer able to access the url?

Reproducido con 2.1.316 (un servidor que arranca y se cierra al instante):

$ claude mcp get sale
sale:
  Scope: Local config (private to you in this project)
  Status: ✘ Failed to connect
  Issue: CONNECTION_CLOSED: Connection closed

Reproducido con 2.1.316 (desde otra carpeta, o con un .mcp.json mal escrito):

No MCP servers configured. Use `claude mcp add` to add a server.

[Failed to parse] Project config (shared via .mcp.json)
 └ [Error] MCP config is not a valid JSON

Causa y arreglo según el mensaje:

  1. ENOENT: el comando del servidor no existe en esa ruta o no está instalado. Ejecuta tú el mismo comando en la terminal (por ejemplo npx -y @playwright/mcp@latest) para ver el error real. Si funciona ahí pero no en Claude Code, revisa con claude mcp get <nombre> que el comando guardado sea el mismo; lo habitual es haber olvidado el -- antes del comando al hacer claude mcp add.
  2. ECONNREFUSED o sin respuesta: la URL es incorrecta o el servidor no está levantado. Pruébala con curl -I <url>. Un 404 o 405 significa que el servidor responde; un 401 o 403, que tienes que autenticarte.
  3. CONNECTION_CLOSED: el proceso arrancó y se cerró. Casi siempre le falta una variable de entorno (una clave de API). Pásala con --env CLAVE=valor en claude mcp add.
  4. No MCP servers configured: los servidores de ámbito local van ligados al proyecto donde los añadiste. Vuelve a añadirlo en este proyecto o usa --scope user. Recuerda que Claude Code solo lee ~/.claude.json y <proyecto>/.mcp.json, no rutas como ~/.claude/mcp.json.
  5. MCP config is not a valid JSON: corrige la sintaxis de .mcp.json. Claude Code lo lee al arrancar, así que reinicia la sesión después de editarlo.
  6. Se agota el tiempo al arrancar: el primer npx puede tardar más de los 30 segundos por defecto. Sube el límite:
MCP_TIMEOUT=60000 claude

Para quitar un servidor roto: claude mcp remove <nombre> -s local.

Compruébalo

Después de cada arreglo, confirma desde la terminal:

claude --version
claude mcp list

Salida esperada: la versión (por ejemplo 2.1.316 (Claude Code)) y cada servidor MCP con ✔ Connected. Dentro de una sesión, /status debe mostrar la cuenta o la clave que esperas y /context debe dejar margen libre en la ventana.

Por qué funciona

Casi todos estos errores vienen de tres sitios distintos y el arreglo depende de cuál: el servicio (500, 529, limitación temporal; se arreglan esperando o cambiando de modelo), tu cuenta o tu credencial (401, 403, límites de uso; se arreglan con /status, /login y revisando ANTHROPIC_API_KEY) o tu equipo (PATH, sandbox, MCP, contexto; se arreglan con configuración local). Identificar el origen primero evita reinstalar cuando la API solo está saturada, o esperar cuando en realidad hay una clave vieja en tu entorno. La lista completa y actualizada de mensajes está en la referencia de errores (también en español), y los de instalación en Troubleshoot installation and login.

Errores típicos

Preguntas frecuentes

¿El error 529 gasta mi límite de uso?

No. Según la documentación oficial, un 529 significa que la API está al límite de capacidad para todos y no descuenta de tu cuota.

¿Cómo sé si Claude Code está caído para todos?

Mira status.claude.com. Si los mensajes de error terminan con otra URL de estado, es la de tu proveedor (Bedrock, Google Cloud, Microsoft Foundry o tu gateway).

¿Pierdo la conversación si cierro Claude Code por un error?

No. Ejecuta claude --resume en la misma carpeta para retomar la sesión.

¿Qué hago con un error que no aparece aquí?

Busca el texto exacto en la referencia de errores oficial, que tiene una tabla de mensajes, y ejecuta /doctor. Si persiste sin incidente publicado, envía /feedback para que Anthropic lo investigue con los detalles de tu petición.

Todas las recetas