guide

Solucionar OpenRouter 429 "Provider Returned Error": Rate Limits, proveedores upstream y opciones de fallback

EvoLink Team

Product Team

13 de mayo de 2026

10 min de lectura

Si sus solicitudes a OpenRouter fallan con 429 o "provider returned error", la solucion depende de donde se origina realmente el fallo.

Estos dos errores se ven similares en sus logs, pero tienen causas raiz diferentes:

429 Too Many Requests: su solicitud fue rechazada porque se alcanzo un rate limit
Provider returned error: OpenRouter acepto su solicitud, pero el proveedor upstream del modelo (OpenAI, Anthropic, Google, etc.) devolvio un error

Confundirlos lleva a aplicar correcciones equivocadas. Esta guia le ayuda a aislar la causa y elegir la respuesta correcta.

Resumen rapido

Un 429 de OpenRouter significa que alcanzo el rate limit o la cuota de OpenRouter.
Un "provider returned error" significa que el proveedor upstream rechazo la solicitud, no OpenRouter.
Revise los encabezados de respuesta y el cuerpo del error para distinguir ambos.
La solucion es diferente: el 429 de OpenRouter requiere cambios de clave o tier; los errores de proveedor requieren diagnostico upstream o cambios de ruta.
Para cargas de trabajo en produccion, disene el fallback antes de que ocurra el error.

Paso 1: Leer la respuesta de error cuidadosamente

Cuando reciba un error, observe estos tres elementos:

Senal	Donde encontrarla	Que le indica
Codigo de estado HTTP	Estado de la respuesta	429 = rate limit; 502/503 = fallo upstream
Cuerpo del mensaje de error	`error.message` en la respuesta JSON	A menudo dice "provider returned error" o muestra un mensaje especifico de rate limit
Encabezados de respuesta	`x-ratelimit-remaining`, `retry-after`	Si OpenRouter mismo le esta limitando

Un 429 tipico de OpenRouter se ve asi:

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

Un error tipico de proveedor se ve diferente:

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

La distincion importa porque requieren soluciones diferentes.

Paso 2: Identificar el origen del error

Use este arbol de decision:

Solicitud fallida
├── HTTP 429 + mensaje de rate limit de OpenRouter
│   → Causa: rate limit a nivel de OpenRouter
│   → Solucion: reducir la tasa de solicitudes, subir de tier o agregar retraso
│
├── HTTP 429 + "provider returned error" en el mensaje
│   → Causa: rate limit del proveedor upstream reenviado
│   → Solucion: verificar cuota del proveedor, cambiar modelo o agregar ruta de fallback
│
├── HTTP 502/503 + "provider returned error"
│   → Causa: caida del proveedor upstream o fallo transitorio
│   → Solucion: reintentar con backoff, cambiar proveedor o usar fallback
│
└── HTTP 400/401 + mensaje de error
    → Causa: solicitud invalida, clave invalida o modelo no encontrado
    → Solucion: verificar clave API, ID del modelo y formato de solicitud

Paso 3: Solucionar el 429 a nivel de OpenRouter

Si el 429 proviene de OpenRouter mismo (no reenviado desde un proveedor), verifique en este orden:

3.1 Verificar su tier de rate limit actual

OpenRouter aplica rate limits segun el tier de su cuenta. Los usuarios del tier gratuito tienen limites significativamente mas bajos que los usuarios de pago.

Accion: Consulte su panel de OpenRouter para ver los limites actuales y el uso.

3.2 Reducir la tasa de solicitudes

Si esta enviando solicitudes mas rapido de lo que su tier permite:

import asyncio
import random

async def call_with_backoff(make_request, max_retries=5):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                # Respect retry-after if present, otherwise use jittered backoff
                delay = min(30, (2 ** attempt) + random.random())
                await asyncio.sleep(delay)
            else:
                raise

3.3 Distribuir el trafico en el tiempo

Las cargas de trabajo de agentes suelen crear patrones de rafaga. En lugar de enviar 50 solicitudes simultaneamente:

Use un semaforo para limitar la concurrencia
Agregue un pequeno retraso entre lotes
Separe las colas de primer plano y segundo plano

Paso 4: Solucionar errores del proveedor upstream

Si el mensaje de error contiene "provider returned error", el problema esta en el upstream. OpenRouter reenvio su solicitud, pero el proveedor del modelo la rechazo.

4.1 Causas upstream comunes

Causa upstream	Que ve usted	Como verificarlo
Rate limit del proveedor	429 reenviado	Verifique si el mismo modelo funciona con una tasa de solicitudes menor
Caida del proveedor	502/503 reenviado	Consulte la pagina de estado del proveedor (ej. status.openai.com)
Modelo obsoleto o no disponible	404 o modelo no encontrado	Verifique que la ID del modelo siga vigente en la lista de modelos de OpenRouter
Restriccion regional	403 o acceso denegado	Algunos proveedores restringen el acceso por geografia
Entrada demasiado grande	400 con mensaje de contexto/tokens	Verifique si su entrada excede la ventana de contexto del modelo

4.2 Cambiar a una ruta de proveedor diferente

OpenRouter enruta las solicitudes a proveedores upstream. Si un proveedor le esta limitando, el mismo modelo podria estar disponible a traves de una ruta diferente.

Verifique si:

El modelo tiene multiples opciones de proveedor en OpenRouter
Puede configurar preferencias de proveedor en su solicitud
Hay un modelo de fallback con capacidades similares disponible

4.3 Agregar logica de reintentos que distinga tipos de error

No reintente todos los errores de la misma manera:

async def smart_retry(make_request, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            error_msg = str(e)

            # Do NOT retry: bad request, auth error, model not found
            if any(code in error_msg for code in ["400", "401", "404"]):
                raise

            # Retry with backoff: rate limit or provider error
            if any(code in error_msg for code in ["429", "502", "503"]):
                delay = min(30, (2 ** attempt) + random.uniform(0, 1))
                await asyncio.sleep(delay)
            else:
                raise

Paso 5: Disenar el fallback antes de que ocurra

En produccion, la pregunta no es si los errores upstream ocurriran -- ocurriran. La pregunta es si su sistema degrada elegantemente o se cae.

Lista de verificacion de fallback

Capa de fallback	Que implementar	Por que
Reintento con backoff	Backoff exponencial con jitter respetando `retry-after`	Maneja fallos transitorios sin amplificar la carga
Fallback de modelo	Si el modelo principal falla, enrutar a una alternativa capaz	Mantiene el flujo de trabajo funcionando cuando una ruta de modelo esta caida
Fallback de proveedor	Si un proveedor devuelve errores, probar una ruta diferente	Reduce la dependencia de un solo proveedor
Cola + circuit breaker	Dejar de enviar a una ruta fallida tras N fallos consecutivos	Previene tormentas de reintentos que empeoran el problema
Degradacion controlada	Contexto mas pequeno, modelo mas economico o respuesta en cache	Mejor que un fallo total para el usuario final

Cuando considerar un gateway API unificado

Si esta construyendo logica de fallback sobre OpenRouter para manejar fallos upstream, en esencia esta construyendo una capa de enrutamiento sobre otra capa de enrutamiento.

En ese punto, puede ser mas simple usar un gateway que maneje el enrutamiento de proveedores, fallback y seleccion de modelos como una funcionalidad integrada, en lugar de codigo a nivel de aplicacion.

El Smart Router de EvoLink maneja esto a nivel de gateway:

Enruta automaticamente entre proveedores
Devuelve el modelo realmente utilizado en la respuesta
Formato de solicitud compatible con OpenAI -- no requiere reescribir codigo
Sin tarifa de enrutamiento adicional

curl https://api.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "evolink/auto",
    "messages": [
      {"role": "user", "content": "Your prompt here"}
    ]
  }'

Esto no elimina la necesidad de logica de reintentos del lado del cliente, pero saca la seleccion de proveedores y el fallback de su codigo de aplicacion.

Arbol de causas de error (referencia)

Solicitud a OpenRouter fallida
│
├── 429 de OpenRouter
│   ├── Limite del tier gratuito → actualizar cuenta
│   ├── Trafico en rafaga → agregar control de concurrencia
│   └── Volumen alto sostenido → verificar limites del tier
│
├── "Provider returned error"
│   ├── Upstream 429
│   │   ├── Rate limit del proveedor → reducir tasa o cambiar proveedor
│   │   └── Cuota compartida agotada → verificar limites a nivel de organizacion
│   ├── Upstream 502/503
│   │   ├── Caida del proveedor → verificar pagina de estado, esperar o cambiar
│   │   └── Fallo transitorio → reintentar con backoff
│   └── Upstream 400
│       ├── Contexto demasiado largo → truncar o cambiar modelo
│       ├── Parametros invalidos → verificar documentacion de la API
│       └── Modelo obsoleto → verificar ID del modelo
│
└── Otros errores
    ├── 401 → clave API invalida
    ├── 404 → modelo no encontrado
    └── Error de red → verificar conectividad

Que hacer a continuacion

Verifique su error actual: Use el Paso 2 para identificar si es un 429 de OpenRouter o un error de proveedor.
Aplique la correccion especifica: No aplique correcciones de rate limit a errores de proveedor ni viceversa.
Agregue logica de reintentos estructurada: Distinga en el codigo entre errores reintentables y no reintentables.
Disene el fallback antes de necesitarlo: Los sistemas en produccion nunca deben depender de una sola ruta upstream.

Articulos relacionados

How to Reduce 429 Errors in Agent Workloads -- patrones mas profundos para trafico en rafaga especifico de agentes
Best OpenRouter Alternatives in 2026 -- compare opciones de enrutamiento cuando los limites de OpenRouter son un problema recurrente
Best AI API Platform for Production Reliability -- framework para elegir una plataforma API de produccion confiable

Explore EvoLink Smart Router

FAQ

Que significa "provider returned error" en OpenRouter?

Significa que OpenRouter recibio su solicitud y la reenvio al proveedor upstream del modelo, pero el proveedor devolvio un error. El error no proviene de OpenRouter, sino de OpenAI, Anthropic, Google o el proveedor que sirve ese modelo.

Es lo mismo un 429 de OpenRouter que un 429 del proveedor upstream?

No. Un 429 a nivel de OpenRouter significa que alcanzo los rate limits propios de OpenRouter. Un 429 a nivel de proveedor reenviado como "provider returned error" significa que el proveedor upstream rechazo la solicitud. Las soluciones son diferentes.

Debo reintentar ante un "provider returned error"?

Depende del tipo de error. Si el upstream devolvio 502/503 (fallo transitorio), reintentar con backoff es razonable. Si devolvio 400 (solicitud invalida) o 404 (modelo no encontrado), reintentar no servira -- corrija la solicitud en su lugar.

Como se si el problema es mi clave API, mi cuota o el proveedor?

Verifique en este orden: (1) Es valida su clave API? Pruebe con una solicitud simple de prueba. (2) Consulte su panel de OpenRouter para ver el uso de cuota y rate limit. (3) Si su clave y cuota estan bien, el error probablemente proviene del proveedor upstream -- revise el mensaje de error para mas detalles.

Puede un gateway API unificado eliminar los errores de proveedor?

Ningun gateway puede evitar que los proveedores upstream fallen. Pero un gateway con enrutamiento y fallback integrados puede cambiar automaticamente a un proveedor o modelo alternativo cuando una ruta falla, reduciendo el impacto en su aplicacion.

Cuando deberia cambiar de OpenRouter a otra solucion de enrutamiento?

Considere el cambio cuando: (1) los errores de proveedor son un problema recurrente en produccion, (2) necesita logica de fallback que OpenRouter no proporciona, (3) su carga de trabajo abarca multiples modalidades (texto + imagen + video), o (4) quiere que las decisiones de enrutamiento se gestionen a nivel de gateway en lugar de en el codigo de la aplicacion.

Todas las Publicaciones

#openrouter 429 #provider returned error #rate limit #solucion de problemas #errores de API de IA