Límites de solicitudes en APIs de video con IA: topes y reintentos

Los límites de solicitudes (rate limits) son esa parte de una API que ignoras hasta un martes por la tarde, cuando un proceso por lotes y el lanzamiento de un producto caen en el mismo minuto y todo empieza a devolver 429. Entonces descubres que tu lógica de reintentos es un setTimeout de un segundo dentro de un bucle, y eso no es esperar de forma progresiva: es la misma estampida a un ritmo un poco más lento.

Así se calculan los límites de eroq, en el orden en que se aplican las cifras, y así se escribe un cliente que se porta bien cuando choca con uno.

Los topes base, por clave y por minuto

Tres cifras, contadas por clave de API en una ventana deslizante de sesenta segundos:

• Chat: 60 solicitudes por minuto. Cubre POST /v1/chat/completions, con o sin streaming. Un stream SSE cuenta una sola vez, en el momento en que lo abres, no por token.
• Imágenes: 20 solicitudes por minuto. Una llamada con un lote de cuatro cuenta como una sola solicitud.
• Video y voz: 6 solicitudes por minuto cada uno.

Seis solicitudes de video por minuto parecen pocas hasta que recuerdas qué es una solicitud de video: un envío, no un render. POST /v1/videos/generations devuelve un id de job al instante y el clip llega minutos después, así que seis envíos por minuto son seis renders nuevos por minuto, que es una cantidad seria de trabajo de producción. La referencia completa del endpoint está en /docs/video.

Fíjate en la unidad: por clave, no por cuenta. Dos claves son dos ventanas independientes. Ese es el mecanismo detrás del consejo de emitir una clave por pipeline: un bucle desbocado en staging solo frena a staging.

El multiplicador del plan

Un plan activo multiplica cada uno de esos topes base, en todas las claves del espacio de trabajo:

• Sin plan y Hobby: 1×
• Creator: 2×
• Studio: 4×
• Team: 6×
• Agency: 8×

Así, los envíos de video pasan de 6 por minuto a 24 en Studio y a 48 en Agency, y el chat pasa de 60 a 240 y 480. El número de claves crece a la par (10 claves en Hobby, 20 en Creator, 50 en Studio, 100 en Team, 200 en Agency), lo que significa que el techo real en un plan grande es el multiplicador por el número de claves que estés dispuesto a gestionar. La tabla completa está en /pricing.

La parte de cada miembro, por encima

Dentro de un espacio de trabajo, el rol de un miembro restringe lo que reciben sus claves. Un Desarrollador o un Administrador recibe toda la asignación del plan; un Creador empieza con la mitad, con la idea de que el trabajo interactivo en el estudio no debería poder dejar sin recursos a un pipeline de producción que comparte el mismo plan.

Un administrador puede restringirlo todavía más para cada miembro, como porcentaje, en la pestaña Miembros de /dashboard/workspace. Ese ajuste solo puede reducir la parte del rol, nunca subirla por encima de lo que el rol concede.

Las cuentas se componen en una sola dirección, así que son fáciles de predecir:

effective limit = base cap × plan multiplier × member share

Un compañero con el rol Creador en un plan Studio, llamando al endpoint de video:

6 × 4 × 0.5 = 12 video submissions per minute, per key

Restringe a ese miembro al 25% y obtiene 6. Aquí hay dos cosas que no pasan, y las dos son deliberadas. Una parte restringida nunca frena los endpoints gratuitos de solo lectura: listar jobs o consultar el saldo de la cuenta sigue funcionando. Y un miembro que no tiene permiso para generar recibe un error de permiso claro en el momento en que se moverían los créditos, no una ristra de 429 misteriosos.

Cómo es realmente un 429

Recibes el código de estado, una cabecera Retry-After en segundos y un cuerpo que nombra el ámbito y el límite que se aplicó:

{
  "error": {
    "message": "Rate limit reached for video (24/min per key). Retry in 37s.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

La cabecera es la parte útil. Como la ventana se desliza, Retry-After no es un tiempo de espera fijo: es el número de segundos que faltan para que la solicitud más antigua de tu ventana actual salga de ella y se libere un hueco. Esperar exactamente ese tiempo es lo correcto; esperar un segundo y volver a intentarlo, no.

Esperar y reintentar como es debido

Cuatro reglas, por orden de prioridad.

1. Respeta Retry-After cuando esté presente. Se calcula a partir de la ventana real, así que gana a cualquier heurística que inventes.

2. Usa backoff exponencial con jitter cuando no esté. Duplicar la espera sin más vuelve a sincronizar a todos tus clientes en el mismo instante de reintento. El jitter completo (un retraso aleatorio entre cero y el techo actual) los reparte.

3. No reintentes errores que no son transitorios. 402 insufficient_credits, 403 plan_required, 403 role_forbidden y un rechazo content_blocked devolverán exactamente la misma respuesta dentro de treinta segundos. Muéstralos. Un 503 model_unavailable significa que el motor no está disponible ahora mismo para tu cuenta: elegir otro motor de /models es mejor respuesta que un bucle de reintentos.

4. Limita la concurrencia en lugar de reintentar contra un muro. Un semáforo dimensionado en tu límite efectivo, o justo por debajo, convierte el límite de solicitudes de un camino de error en un problema de planificación, que es donde debe estar.

Aquí está todo, lo bastante corto para copiarlo y pegarlo:

const sleep = ms => new Promise(r => setTimeout(r, ms))

async function submitVideo(body, { attempts = 5 } = {}) {
  let delay = 1000
  for (let attempt = 1; attempt <= attempts; attempt++) {
    const res = await fetch('https://eroq.ai/v1/videos/generations', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    })

    if (res.ok) return res.json()          // 202 with a job id
    if (res.status !== 429) {              // 402/403/503 are not transient
      throw new Error(`${res.status} ${(await res.json()).error?.code}`)
    }

    const header = Number(res.headers.get('retry-after'))
    const wait = Number.isFinite(header) && header > 0
      ? header * 1000
      : Math.random() * delay              // full jitter
    await sleep(wait)
    delay = Math.min(delay * 2, 30_000)
  }
  throw new Error('rate limited after all attempts')
}

Cinco intentos es un techo razonable para un flujo de cara al usuario. Para un worker por lotes, elimina por completo el bucle de reintentos y deja que una cola con una tasa de envío fija marque el ritmo: chocarás con el límite muchas menos veces y, cuando ocurra, la cola es el lugar natural para esperar.

Qué límite alcanzas primero en la práctica

En la práctica, la mayoría de los equipos nunca toca el tope de video. Seis envíos por minuto son 360 por hora, y el saldo se agota mucho antes de que el limitador se queje: los créditos y el tiempo real de render son las restricciones que de verdad mandan en el trabajo de video, y por eso el artículo sobre presupuesto y /pricing importan aquí más que este.

El chat es lo contrario. Sesenta solicitudes por minuto en un plan gratuito o Hobby se alcanzan de verdad en cuanto una app de compañero virtual o un producto de rol tiene una noche movida, y cada turno de un usuario es una solicitud. Si construyes sobre el chat, cuenta con el multiplicador, reparte la carga entre claves por superficie y lee la guía práctica de streaming SSE antes de diseñar el camino de reintentos: un stream que muere a mitad de respuesta necesita un tratamiento distinto al de una solicitud que nunca empezó.

Las imágenes quedan en medio. Veinte por minuto es de sobra para el uso interactivo y se queda justo para un trabajo masivo de catálogo, que es otro argumento a favor de una cola que controles tú en lugar de un abanico de solicitudes en paralelo.

Preguntas frecuentes

¿Los límites de solicitudes de eroq son por clave o por cuenta?

Por clave. Cada clave de API tiene su propia ventana deslizante de un minuto, y por eso emitir una clave por entorno o por pipeline evita que un bucle desbocado frene todo lo demás en el espacio de trabajo.

¿Mejorar mi plan sube los límites de solicitudes?

Sí. Los topes documentados son la base y el plan los multiplica en cada clave: 2× en Creator, 4× en Studio, 6× en Team y 8× en Agency. El número de claves también sube con el plan.

¿Qué hago cuando recibo un 429 del endpoint de video?

Lee la cabecera Retry-After, espera exactamente ese tiempo y vuelve a intentarlo una vez. Si no viene la cabecera, usa backoff exponencial con jitter completo y limita tu concurrencia para que el siguiente lote no choque contra el mismo muro.

Lee la referencia de los endpoints en /docs y luego mira qué multiplica tu plan en /faq.