Claude Code con OpenRouter: Límites, errores y alternativas para agentes de programación

Pero "funciona" no es lo mismo que "funciona de forma fiable en producción." Los equipos que enrutan tráfico de agentes de programación a través de OpenRouter acaban encontrándose con tres categorías de fricción:

1. Errores difíciles de diagnosticar — porque OpenRouter añade su propia capa de errores sobre los proveedores upstream
2. Costos difíciles de predecir — porque las tarifas de enrutamiento, los recargos de proveedores y el desperdicio por reintentos se acumulan
3. Límites que interactúan entre sí — porque los límites de tasa de OpenRouter y los de Anthropic se aplican simultáneamente

Esta guía cubre lo que realmente sale mal y cuándo las alternativas tienen más sentido.

Resumen

• OpenRouter funciona bien para experimentar con Claude Code y para uso a pequeña escala.
• A escala de equipo, el diagnóstico de errores, el seguimiento de costos y la acumulación de límites de tasa se convierten en fricción real.
• Los errores más comunes son 429 (límite de tasa) y "provider returned error" — y requieren soluciones diferentes.
• Las alternativas incluyen Anthropic directo (más simple pero sin fallback), gateways unificados (enrutamiento + fallback integrados) y proxies autoalojados (máximo control).
• Usa la tabla de decisión de abajo para elegir según tu carga de trabajo.

Cómo configurar Claude Code con OpenRouter

La configuración es mínima:

{
  "apiProvider": "openrouter",
  "openRouterApiKey": "sk-or-v1-..."
}

Una vez configurado, puedes usar modelos Claude a través de los IDs con namespace de OpenRouter:

anthropic/claude-sonnet-4-20250514
anthropic/claude-opus-4-20250514

Esto funciona. Los problemas empiezan cuando tu carga de trabajo crece.

Límites comunes en cargas de trabajo de agentes de programación

Acumulación de límites de tasa

Cuando enrutas Claude Code a través de OpenRouter, se aplican dos sistemas de límites de tasa:

Puedes alcanzar cualquiera de los dos de forma independiente. Un 429 proveniente de los límites propios de OpenRouter se ve diferente a un 429 transmitido desde Anthropic — pero ambos detienen tu agente de programación.

Ventana de contexto y presión de tokens

Los modelos Claude soportan hasta 200K tokens de contexto. Los agentes de programación envían habitualmente bases de código completas como contexto. A través de OpenRouter, esto implica:

• Costos de tokens más altos (OpenRouter transmite los precios del proveedor más cualquier recargo)
• Se aplican ambos límites de TPM
• Las solicitudes grandes tienen más probabilidad de provocar timeouts — y el comportamiento de timeout difiere de los límites de tasa

Falta de visibilidad de costos

OpenRouter proporciona información de facturación, pero los equipos que usan agentes de programación a menudo necesitan:

• Seguimiento de costos por desarrollador
• Atribución de costos por proyecto o repositorio
• Desglose de costos por modelo (Opus vs. Sonnet vs. alternativas más económicas)
• Visibilidad del costo de reintentos (¿cuánto cuestan las solicitudes fallidas?)

Esto no siempre es fácil de extraer de la interfaz de facturación de OpenRouter.

Errores comunes y cómo diagnosticarlos

Error 1: 429 de OpenRouter mismo

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded."
  }
}

Error 2: "Provider returned error"

{
  "error": {
    "code": 502,
    "message": "Provider returned error: [upstream details]"
  }
}

Error 3: Modelo no encontrado

{
  "error": {
    "message": "Model not found"
  }
}

Error 4: Timeout en tareas de programación largas

Los agentes de programación a menudo generan salidas extensas (refactorizar archivos completos, escribir suites de tests). Si el timeout de tu cliente es más corto que el tiempo de generación, la solicitud falla — pero los tokens ya fueron consumidos.

Tabla de decisión para enrutamiento de agentes de programación

Cuándo quedarse con OpenRouter

OpenRouter es una elección razonable cuando:

• Todavía estás experimentando con qué modelos funcionan mejor para tus tareas de programación
• Tu equipo es lo suficientemente pequeño como para que la contención de límites de tasa sea rara
• Valoras la variedad de modelos por encima de la optimización de costos
• No necesitas atribución de costos por proyecto

No cambies solo porque tuviste un mal día con errores. Los problemas transitorios ocurren en cualquier plataforma.

Cuándo considerar alternativas

Considera el cambio cuando:

• Los errores 429 son recurrentes — no ocasionales, sino un problema de producción semanal
• Los costos son difíciles de explicar — no puedes responder "¿cuánto costaron los agentes de programación este sprint?"
• Se necesita fallback — cuando OpenRouter o su upstream están caídos, todo tu flujo de programación se detiene
• Necesitas multimodal — tu flujo incluye generación de imágenes o video junto con programación, y quieres una sola superficie API

Alternativa: Anthropic directo

{
  "apiProvider": "anthropic",
  "anthropicApiKey": "sk-ant-..."
}

Pro: Lo más simple y directo. Contra: Sin fallback, solo Claude, sin enrutamiento de costos.

Alternativa: EvoLink (Gateway unificado)

{
  "apiProvider": "openai-compatible",
  "openAiBaseUrl": "https://api.evolink.ai/v1",
  "openAiApiKey": "your-evolink-key"
}

Pro: Compatible con OpenAI, enrutamiento y fallback a nivel de gateway, acceso multimodelo, optimización de costos. Contra: Otro proveedor en la cadena.

Alternativa: LiteLLM (Self-hosted)

Pro: Control total, autoalojado, código abierto. Contra: Tú te encargas de la infraestructura, el despliegue y la respuesta a incidentes.

Ruta de migración: OpenRouter → Alternativa

Si decides cambiar, la migración es mínima porque Claude Code soporta el cambio de proveedor a través de la configuración:

Artículos relacionados

• Claude Code Router: Provider Options and Production Routing Setup — comparación completa de proveedores para Claude Code
• One Gateway for 3 Coding CLIs — configurar Gemini CLI, Codex CLI y Claude Code a través de un solo gateway
• Fix OpenRouter 429 "Provider Returned Error" — depurar errores específicos de OpenRouter
• Best OpenRouter Alternatives in 2026 — comparación más amplia de alternativas
• Context Length Exceeded in LLM API Calls — manejar contexto de programación grande

FAQ

¿Es OpenRouter suficiente para Claude Code?

Para uso personal y equipos pequeños, sí. Para equipos de producción con 3+ desarrolladores, tráfico en picos y requisitos de seguimiento de costos, probablemente encontrarás fricción con el diagnóstico de errores, la acumulación de límites de tasa y la visibilidad de costos. Evalúa si la fricción es manejable antes de cambiar.

¿Cuál es el error más común al usar Claude Code con OpenRouter?

Los errores 429 de límite de tasa y "provider returned error" son los más comunes. La clave es distinguir si el error proviene de OpenRouter mismo o del proveedor upstream (Anthropic). Requieren soluciones diferentes.

¿Puedo cambiar de OpenRouter a otro proveedor sin modificar mi código?

Si tu nuevo proveedor es compatible con OpenAI (como EvoLink), el cambio es solo de configuración: actualiza la URL base y la clave API en los ajustes de Claude Code. No se necesitan cambios de código.

¿Enrutar a través de OpenRouter cuesta más que Anthropic directo?

Depende. OpenRouter transmite los precios del proveedor y puede añadir tarifas de enrutamiento o plataforma. El costo efectivo también incluye el desperdicio por reintentos en el manejo de errores. Compara tu gasto total (incluyendo reintentos y solicitudes fallidas) para evaluar la diferencia real de costo.

¿Debería usar Claude Opus o Sonnet para agentes de programación?

Opus es más capaz para razonamiento complejo y refactorizaciones grandes. Sonnet es más rápido y económico para tareas rutinarias. Muchos equipos usan Opus para problemas difíciles y Sonnet para todo lo demás — ahí es donde el enrutamiento de modelos se vuelve valioso.

¿Cómo hago seguimiento de costos por desarrollador a través de OpenRouter?

OpenRouter proporciona datos de uso, pero la atribución por desarrollador generalmente requiere claves API separadas por desarrollador o un wrapper que etiquete las solicitudes. Un gateway unificado con seguimiento por clave puede simplificar esto.