Límite alcanzado durante una sesión de código
La cuenta, workspace, modelo o ruta envía más solicitudes o tokens de los permitidos.
Reducir agentes paralelos · Recortar el contextoSolución de problemas de Claude Code API
Resuelve límites, errores 500, sobrecarga 529 y confusión con API Keys
Un único procedimiento para configuración de API Keys, Pro o Max frente a facturación API, endpoints compatibles con Messages, límites, errores del servidor y rutas saturadas.
claude-code-diagnostics
$ claude-code run --model claude-sonnetError de API: límite de velocidad alcanzadostatus=429 route=messages tokens=128k retries=3siguiente: reducir concurrencia, verificar key y reintentar con espera
4 familias de errores1 procedimiento0 páginas sin contenido útil
Señales de la comunidad
Lo que los desarrolladores preguntan repetidamente en público
Los patrones recurrentes de Reddit y X se convierten en indicaciones de diagnóstico estables y verificables.
API Key frente a suscripción Pro o Max
Comprueba la key activa, la Base URL y la fuente de facturación. No supongas que la suscripción y los créditos API comparten saldo.
Comprobar acceso al modelo · Separar inicio de sesión y facturación APIErrores 500 o 529 en bucles de agentes
El proveedor o la ruta devolvió un fallo del servidor. Un reintento puede funcionar; los fallos repetidos requieren evidencia de ruta. El servicio upstream está bajo mucha carga. Cambiar la API Key normalmente no lo resuelve.
Capturar request id · Aplicar backoffMapa de errores
Empieza por el código de estado, no por el rumor
La solución más rápida separa problemas de key, cuota, servidor y sobrecarga.
429
Límite de velocidad alcanzado
La cuenta, workspace, modelo o ruta envía más solicitudes o tokens de los permitidos.
- Reducir agentes paralelos
- Recortar el contexto
- Reintentar con backoff
- Comprobar cuota y límites del modelo
500
Error del servidor API
El proveedor o la ruta devolvió un fallo del servidor. Un reintento puede funcionar; los fallos repetidos requieren evidencia de ruta.
- Capturar request id
- Reintentar una vez
- Cambiar de ruta si se repite
- No empezar reescribiendo prompts
529
Sobrecarga
El servicio upstream está bajo mucha carga. Cambiar la API Key normalmente no lo resuelve.
- Aplicar backoff
- Usar un modelo alternativo
- Reducir la solicitud
- Consultar canales de soporte/estado
401/403
Problema de API Key o permisos
Claude Code no usa la key esperada o esta no puede acceder al modelo o endpoint solicitado.
- Confirmar ANTHROPIC_API_KEY
- Comprobar Base URL
- Comprobar acceso al modelo
- Separar inicio de sesión y facturación API
Procedimiento
Antes de cambiar código, reúne estos datos
- Anota el texto exacto del error, estado HTTP, modelo, endpoint y hora.
- Confirma si Claude Code usa una key directa de Anthropic o la Base URL de un gateway compatible.
- Comprueba facturación y cuota de la API por separado del estado de Claude Pro o Max.
- Para 429, reduce concurrencia y contexto antes de cambiar de proveedor.
- Para 500 o 529, reintenta una vez con backoff y compara otra ruta o modelo alternativo.
- Si usas gateway, verifica endpoint compatible con Messages, ruta del modelo, caché y soporte.
Pro o Max no es lo mismo que la facturación API
Comprueba la key activa, la Base URL y la fuente de facturación. No supongas que la suscripción y los créditos API comparten saldo.
Obtener acceso API¿Usas gateway? Verifica el endpoint Messages
Los clientes tipo Claude Code suelen necesitar un endpoint compatible con Messages, una API Key válida y una ruta de modelo adecuada.
Consultar documentaciónPreguntas frecuentes
Errores de Claude Code API
¿Por qué Claude Code dice que se alcanzó el límite?
La cuenta, workspace, modelo o ruta envía más solicitudes o tokens de los permitidos. Reducir agentes paralelos · Recortar el contexto · Reintentar con backoff · Comprobar cuota y límites del modelo
¿Claude Pro o Max incluye una API Key?
Comprueba la key activa, la Base URL y la fuente de facturación. No supongas que la suscripción y los créditos API comparten saldo.
¿Qué hago ante un error API 500?
El proveedor o la ruta devolvió un fallo del servidor. Un reintento puede funcionar; los fallos repetidos requieren evidencia de ruta. Capturar request id · Reintentar una vez · Cambiar de ruta si se repite · No empezar reescribiendo prompts
¿Qué significa sobrecarga 529?
El servicio upstream está bajo mucha carga. Cambiar la API Key normalmente no lo resuelve. Aplicar backoff · Usar un modelo alternativo · Reducir la solicitud · Consultar canales de soporte/estado
Fuentes
Dónde verificar las reglas actuales
Usa la documentación oficial para límites y significado de errores. La comunidad muestra demanda, no es la fuente de verdad.