Errores de límite de tasa de OpenRouter en Hermes Agent

Tu agente se paró a media conversación

Vas por el tercer turno de una charla con Hermes Agent que por fin era útil cuando la respuesta llega vacía y el log muestra una línea roja: 429 Too Many Requests. O peor, un 402 Payment Required porque el modelo rechazó la petición de plano. El agente que hace una hora iba fino ahora es un muro de errores de reintento y estás a una sesión de debug de cambiar de proveedor.

Los códigos de error de OpenRouter son precisos si sabes qué significa cada uno. 429 es límite de tasa y viene de tres sitios distintos. 402 es agotamiento de crédito y no se comporta como un 429. 503 es indisponibilidad del proveedor upstream y es el único que puedes automatizar sin dolor. Cada uno tiene una solución concreta, y el array models de Hermes Agent convierte la mayoría en anécdota.

Cómo leer los códigos de error de OpenRouter de un vistazo

Antes de tocar la config, entiende qué te está diciendo la API. OpenRouter documenta estos códigos de forma explícita y los números importan.

Un 429 y un 402 se parecen en la terminal pero requieren respuestas opuestas. Reintentar un 402 en bucle solo quema tu presupuesto de reintentos mientras el saldo sigue a cero. Reintentar un 429 con cabeza es todo el juego.

El otro detalle que merece la pena leer es error.metadata.provider_code. Cuando un 429 viene del proveedor upstream que atiende tu petición (Anthropic, DeepSeek, OpenAI, Groq), OpenRouter reenvía el código de error original de ese proveedor en ese campo. Eso distingue un límite de plataforma de OpenRouter de un límite del inquilino upstream, y cada uno se arregla de una manera.

Causa 1: tope diario del plan gratuito de OpenRouter

Síntoma: ayer iba todo, esta mañana también, y ahora cada petición devuelve 429 aunque apenas mandas tráfico. Suele aparecer tras unos 20 minutos de una sesión normal de Hermes.

Qué está pasando: el plan gratuito de OpenRouter permite 20 peticiones por minuto contra modelos gratuitos, con un tope de 50 al día. Un ingreso único de 10 dólares en créditos sube el mínimo diario de 50 a 1.000 de forma permanente. El bucle de herramientas de Hermes Agent (un turno es una llamada a la API, más los reintentos) agota un día de 50 peticiones dentro de una sola conversación mediana.

Comprueba primero: confirma que el modelo en tu config es del plan gratuito. Los modelos gratuitos de OpenRouter llevan el sufijo :free en su slug (deepseek/deepseek-v4-flash:free). Si tu línea model: termina en :free, este tope aplica.

Solución inmediata: añade 10 dólares en créditos en el panel de OpenRouter. El tope diario salta a 1.000/día para siempre, suficiente para un usuario normal de Hermes.

Solución de fondo: deja de enrutar tráfico de producción por un modelo gratuito. Los modelos gratuitos son para evaluar, no para un agente en marcha. Cambia al mismo modelo sin :free y paga la tarifa (DeepSeek V4-Flash sin el sufijo cuesta 0,14 $/M input, así que un día de uso de Hermes son unos céntimos). La matemática completa de precios está en el modelo de OpenRouter más barato para Hermes Agent.

Causa 2: límite de tasa del proveedor upstream (429 con provider_code)

Síntoma: estás en un modelo de pago, los créditos están sanos y aun así te llega un 429 cuando Hermes tiene actividad. El cuerpo de la respuesta contiene error.metadata.provider_code con un valor tipo rate_limit_exceeded o insufficient_quota.

Qué está pasando: OpenRouter no impone topes duros a los modelos de pago, pero el proveedor upstream sí. Anthropic, OpenAI y DeepSeek aplican límites por cuenta según tu nivel de contrato. Cuando OpenRouter enruta tu petición al upstream, este la rechaza y OpenRouter reenvía el rechazo como 429.

Diagnóstico:

• Lee error.metadata.provider_code. Si dice rate_limit_exceeded, es este caso.
• Comprueba si la petición saltó en un pico (docenas de turnos en una ventana corta) o en régimen estable. Los picos activan límites por minuto, el tráfico sostenido los diarios.
• Confirma el modelo. Algunos modelos se enrutan por un único proveedor con un tope estrecho (los modelos con marca Anthropic vía OpenRouter comparten los límites de la cuenta propia de Anthropic).

Soluciones:

• Respeta la cabecera Retry-After de la respuesta. Tanto en 429 como en 503, OpenRouter devuelve un Retry-After en segundos. Espera ese tiempo antes de reintentar y, si aún así falla, usa backoff exponencial con jitter.
• Configura una cadena de modelos de fallback (Causa 4 más abajo). El array de modelos es la solución más efectiva aquí, porque Hermes reintenta automáticamente con el siguiente modelo en vez de fallar el turno.
• Si un modelo concreto no para de tropezar, plantéate BYOK. Traer tu propia clave de Anthropic u OpenAI a OpenRouter te da los límites de tu propia cuenta upstream en vez de compartir el pool de OpenRouter.

Causa 3: los créditos se acabaron a media conversación (402)

Síntoma: el agente aguantó los primeros 30 turnos y ahora cada petición devuelve 402 insufficient_credits. El panel de OpenRouter marca saldo de 0,00 $.

Qué está pasando: OpenRouter es un saldo prepago, no una factura mensual. Cuando el saldo llega a cero, cada petición se rechaza con 402 hasta que recargas. Los usuarios de modelo gratuito también ven 402 cuando se agota el cupo gratuito del día (usa el mismo código que la falta de crédito, lo cual confunde pero es coherente con la documentación de OpenRouter).

Soluciones:

• Activa el auto-topup en el panel de OpenRouter. Fija un umbral (p. ej. añadir 10 $ automáticos cuando el saldo baje de 2 $). Es la única medida que evita 402 en producción.
• Fija un tope de gasto mensual en el mismo panel para que el auto-topup no acabe en un mes malo silencioso.
• Si estás usando BYOK en el plan Starter de Hermify, la clave de OpenRouter es tuya y el saldo también es tuyo de recargar. Hermify no adelanta créditos por ti.

No implementes reintentos cliente para el 402. Cada reintento es otra llamada que también devuelve 402, y OpenRouter las cuenta contra tu límite aunque fallen.

Causa 4: no hay cadena de fallback configurada

Síntoma: cualquier caída puntual de un modelo en la red de proveedores de OpenRouter te tumba el agente entero hasta que el upstream se recupera. Un 429 en el modelo principal se convierte en una sesión rota.

Qué está pasando: por defecto, Hermes Agent envía una petición nombrando exactamente un modelo. Si ese modelo tiene límite de tasa o si todos sus proveedores están al máximo, OpenRouter devuelve el error y Hermes no tiene a dónde enrutar. Te comes una línea roja en el log y el turno se pierde.

La solución es el parámetro models de OpenRouter, que acepta un array de modelos en orden de prioridad. Si el primero devuelve error, OpenRouter prueba el siguiente, luego el siguiente. Solo cuando el último también falla, el error vuelve a Hermes.

Configura una cadena de 3 modelos de fallback en ~/.hermes/config.yaml. Un ejemplo con forma de producción:

provider: openrouter
openrouter_api_key: sk-or-tu-clave-aqui
model: deepseek/deepseek-v4-pro
fallback_models:
  - anthropic/claude-haiku-4-5
  - google/gemini-2.5-flash
  - openai/gpt-4.1-mini

Esa cadena te da un primario fuerte (DeepSeek V4-Pro para razonamiento con muchas herramientas), un secundario rápido y fiable de otra familia de proveedores y dos fallbacks más en nubes distintas. Si DeepSeek está degradado, la petición se enruta a Anthropic sin perder el turno. El post sobre el mejor proveedor de modelos para Hermes Agent tiene más sobre los trade-offs entre familias de proveedores.

Reglas prácticas para la cadena:

• Elige modelos de familias de proveedores distintas. Dos modelos de OpenAI caen a la vez durante un incidente de OpenAI.
• Ordena por calidad primero, coste después. La cadena baja de arriba abajo y se detiene en el primer éxito.
• Mantenla entre 3 y 5 entradas. Diez fallbacks son diez reintentos secuenciales en un mal día, peor que un único fallo ruidoso.

Causa 5: tormentas de reintentos del propio Hermes

Síntoma: un solo 429 desemboca en cientos de peticiones fallidas en el log, cada una empeorando el límite de tasa. El panel muestra un pico de peticiones justo cuando se rompió todo.

Qué está pasando: sin backoff exponencial, Hermes reintenta una petición limitada de inmediato, lo cual activa el mismo límite, que reintenta otra vez. El bucle de reintentos convierte un error recuperable en una caída autoprovocada. Es la versión OpenRouter del clásico stampede de rate limit del lado cliente.

Soluciones:

• Comprueba que Hermes está respetando Retry-After. Las versiones modernas lo hacen por defecto; algunos forks antiguos, no. Mira la versión con hermes --version y actualiza si vas por detrás.
• Configura una cola con token bucket si corres Hermes contra una cuenta de un solo inquilino. Forzar un mínimo de 3 segundos entre peticiones elimina los 429 del todo en un setup de un usuario.
• Si el bucle de reintentos ya ocurrió, espera 5 minutos antes de reiniciar el agente. El rate limiter de OpenRouter tiene una ventana de calentamiento y los reinicios inmediatos alargan el bloqueo.

El mismo patrón de fallo aparece en cualquier integración de API de alto volumen, no solo OpenRouter. Ver debugging y observabilidad de Hermes Agent para las convenciones de logs que hacen esto diagnosticable.

Cuándo dejar de vigilar al proveedor

Cada solución de este post es una corrección pequeña de cómo está cableada la capa de modelos. El array models más el auto-topup en OpenRouter cubren el 90 % de lo que se rompe. El resto es paciencia y el manejo correcto de Retry-After.

Lo que quema tiempo es descubrir todo esto la tarde en la que tu agente se para a media faena, y darte cuenta entonces de que el tope gratuito saltó, la cadena de fallback nunca se configuró y el bucle de reintentos convirtió un traspié pequeño en una caída de dos horas. Si prefieres no aprender la taxonomía de errores de OpenRouter por las malas, Hermify ejecuta un Hermes Agent gestionado en Telegram con la cadena de fallback ya cableada, una clave de OpenRouter medida (traes la tuya o usas la nuestra) y un umbral de topup que te mantiene por encima de cero. Tu clave BYOK sigue siendo tuya, pero dejas de ser tú quien está de guardia con los 429.

Empieza con Hermify y sáltate el postmortem de la tormenta de reintentos.

Sources

• OpenRouter API credit and rate limits
• OpenRouter model fallbacks documentation
• OpenRouter reliability and failover explainer
• OpenRouter free tier 2026 breakdown
• Handling OpenRouter 429 with retry strategies