Límites de solicitudes

Un límite de solicitudes restringe cuántas solicitudes puedes enviar en un período breve. Si lo superas, la API responde 429 («demasiadas solicitudes») en lugar de ejecutar el trabajo e indica cuánto debes esperar. Es una protección contra scripts descontrolados, no una cuota sobre cuánto contenido puedes generar.

Resumen de límites

Dos grupos de capacidad por cuenta: lecturas y escrituras

La API —todo lo incluido en /api/v1/* y los endpoints compatibles de /v1/* y /v1beta/*— limita las solicitudes por cuenta, no por clave: si el límite fuera por clave, bastaría con crear más claves para eludirlo.

Las lecturas y escrituras se contabilizan en dos grupos de capacidad separados, con el mismo límite. El umbral de protección predeterminado es de 1,000 solicitudes cada 10 segundos en cada uno: unas 100 RPS sostenidas (solicitudes por segundo), con una ráfaga de 1,000. Es una protección general contra el abuso y los clientes descontrolados, no una cuota reducida para el tráfico normal de generación de pago.

Se utiliza un mecanismo de token bucket en lugar de un contador con ventanas fijas: tiene capacidad para 1,000 tokens y se repone a lo largo de 10 segundos, aproximadamente 100 tokens por segundo. Cada solicitud consume un token y estos se recuperan de forma continua. A diferencia de una ventana fija, este mecanismo evita un salto brusco de capacidad al cambiar de período.

upload-url tiene su propia protección general de 1,000 solicitudes cada 10 segundos, además del límite de escritura anterior. Protege por separado la autorización de escritura en el almacenamiento de objetos; las subidas normales no deberían acercarse a ella.

usage tiene una protección adicional mucho más estricta: 30 solicitudes por minuto, además del límite de lectura anterior. Como agrega tareas históricas, cada llamada requiere mucho más trabajo que una lectura normal y la protección general no basta. Úsalo para conciliar el uso, no como endpoint de consultas continuas. Este límite tampoco permite pasar el tráfico cuando no puede decidir: siempre devuelve 429 si el sistema de límites no está disponible, mientras que otros grupos pueden configurarse para permitirlo.

URL de subida que todavía no utilizaste

Por separado, una cuenta puede mantener como máximo 128 URL de subida aún no utilizadas, o 1 GiB de tamaño declarado de archivos entre todas ellas. Solicitar otra devuelve 429 con Too many pending uploads; finish existing uploads before requesting more y sin Retry-After.

Esperar no ayuda en este caso, así que no dejes que un bucle de reintentos genérico lo intente indefinidamente. Sube y confirma los archivos para los que ya solicitaste una URL, o deja que sus URL venzan, lo que tarda unos 20 minutos; al hacerlo, se libera la capacidad inmediatamente. Este error suele indicar que un script solicita URL de subida en lote y después no las utiliza. Consulta Medios.

Todos los grupos de capacidad

Los límites se aplican por grupo de endpoints, de modo que todos los endpoints de un mismo grupo comparten una cadena de middleware. Como consumidor de la API, puedes encontrarte con los primeros cinco:

Estas cifras son valores predeterminados que podemos cambiar sin publicar una versión nueva. Tu capacidad actual siempre aparece en el encabezado X-RateLimit-Limit y en Resumen de la consola. Confía en el encabezado y no fijes los valores predeterminados en el código del cliente.

Encabezados de respuesta

Una respuesta normal de una cuenta con la capacidad predeterminada incluye:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

Cómo se presenta un límite

{
  "code": 429,
  "msg": "Too many requests. Retry in a moment",
  "request_id": "req_…"
}

Estado HTTP 429, con Retry-After.

Cómo gestionarlo

Lee Retry-After. No envíes solicitudes insistentemente a un intervalo fijo. Los ejemplos se detienen después de cinco intentos, lo que también impide que el 429 de «subidas pendientes» descrito anteriormente provoque un bucle infinito.

async function callRespectingLimits(url, init) {
  for (let i = 0; i < 5; i++) {
    const res = await fetch(url, init);

    if (res.status !== 429) return res;

    // The server already told you how long to wait; don't guess
    const wait = Number(res.headers.get('retry-after') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('persistently rate-limited');
}

import time, requests


def call_respecting_limits(method: str, url: str, **kwargs) -> requests.Response:
    for _ in range(5):
        res = requests.request(method, url, **kwargs)

        if res.status_code != 429:
            return res

        # The server already told you how long to wait; don't guess
        time.sleep(float(res.headers.get("retry-after", 1)))

    raise RuntimeError("persistently rate-limited")

La concurrencia es una cuestión independiente

Lo que realmente limita las tareas en curso, sin que ninguno de estos factores sea el límite de solicitudes:

• Saldo disponible: cada tarea en curso retiene fondos. Cuando se agota el saldo, las tareas nuevas reciben 40201.
• Límites de gasto: los límites diario, mensual y total de cada clave, los límites diario y mensual del equipo (para las claves que pertenecen a un equipo) y el límite diario de la plataforma. Alcanzar cualquiera de ellos devuelve 40202. Consulta Límites de gasto.
• Capacidad de ejecución: si un modelo no puede ejecutarse en absoluto, recibes 50301.

Por eso, si quieres más tareas ejecutándose simultáneamente, normalmente necesitas añadir saldo o aumentar un límite de gasto, no aumentar el límite de solicitudes.

Cómo solicitar más capacidad

La capacidad actual aparece en Resumen de la consola. Para pedir más, abre una conversación en Soporte, con el tema Integración de API, y describe tu tráfico: solicitudes máximas por segundo, si ejecutas lotes y qué tamaño alcanzan. Esa información agiliza considerablemente la revisión.

Mientras tanto, mantén acotada la concurrencia del cliente y respeta Retry-After. Elige el máximo de concurrencia según la carga de trabajo, el tiempo de generación y el saldo disponible, en lugar de reducirlo artificialmente para ajustarlo al límite predeterminado de solicitudes.

Cuando el propio sistema de límites no está disponible

Los límites de solicitudes dependen de un contador externo. Si falla, la configuración determina qué ocurre: permitir el tráfico para seguir prestando servicio o rechazarlo para proteger la capacidad. Rechazar es la opción predeterminada: «no pudimos leer la configuración» nunca debe convertirse en «no hay límite».

Cuando está configurado para rechazar, recibes 429 con Retry-After: 1, no 500. Es deliberado: 500 indica que el servicio está fallando y la mayoría de los SDK lo reintentan inmediatamente, aumentando la carga durante un incidente. 429 con Retry-After indica que debes reducir el ritmo y volver más tarde, que es lo que hace falta.

Por tanto, no interpretes 429 como prueba de que enviaste demasiado rápido. Respetar Retry-After es la respuesta correcta en ambos casos.