Límites de velocidad

La API programática aplica un límite de solicitudes sencillo por cuenta, además de la cuota de créditos mensual. En esta página se explica en qué consiste dicho límite, cómo se calcula y cómo reducir el número de solicitudes de forma adecuada.

El límite#

En la práctica: una solicitud por segundo de media, con picos de hasta 60 solicitudes permitidos en cualquier intervalo de 60 segundos.

Cuando se supera el límite, la siguiente solicitud devuelve:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": "Rate limit exceeded. Max 60 requests per minute."
}

La solicitud 429 queda registrada, lo cual está bien: caduca al salir del intervalo de 60 segundos, como cualquier otra solicitud.

Cómo funciona la ventana#

El limitador es una ventana móvil, no un intervalo fijo:

1. Cada vez que realizas una solicitud, el servidor cuenta cuántas de tus solicitudes se han recibido en los últimos 60 segundos.
2. Si ese recuento ya es ≥ 60, la solicitud se rechaza con 429.
3. De lo contrario, el proceso continúa, se registra y contribuye a futuras ventanas.

Así que una ráfaga de 60 solicitudes a t = 0 se despeja a las t=60, no al comienzo del minuto siguiente. No hay Retry-After encabezado: espera aproximadamente 1 segundo y vuelve a intentarlo, o retrocede como se indica a continuación.

Estrategia de retroceso#

Un bucle pragmático:

async function withRetry(fn, { maxAttempts = 6, baseMs = 1000 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const isRateLimited =
        /Rate limit exceeded/.test(err.message);
      const isUpstream5xx =
        /Upstream error/.test(err.message);

      if (!isRateLimited && !isUpstream5xx) throw err;
      if (attempt >= maxAttempts) throw err;

      const delay = baseMs * Math.pow(2, attempt - 1) + Math.random() * 250;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Notas:

• Utiliza un retroceso exponencial con fluctuación. Un piso setTimeout(1000) en cada nuevo intento entrará en conflicto consigo mismo si se ejecuta en paralelo.
• No volver a intentarlo en 403, 404, 401, o el agotamiento del crédito 429. Esos no se recuperarán en un minuto.
• Intentos de tapón. Seis intentos con baseMs=1000 ya cubre aproximadamente 1 minuto de retardo; si sigues estando limitado por la tasa después de eso, significa que mantienes un ritmo superior a 60 por minuto y necesitas menos trabajadores simultáneos, no más reintentos.

Diseñar dentro de los límites#

El límite se aplica por usuario, no por dirección IP ni por clave; generar varias claves no lo aumenta.

Límite de solicitudes frente a créditos#

En la práctica, las cargas de trabajo continuadas agotan la cuota de créditos mucho antes de alcanzar el límite de velocidad. El límite de velocidad existe principalmente para evitar bucles incontrolados.

Cómo determinar la causa de un error 429#

Tanto el límite de tarifas por minuto como el límite de crédito mensual devuelven un 429 código de estado. Puedes distinguirlos examinando el cuerpo de la respuesta:

if (res.status === 429) {
  const body = await res.json();
  if (body && body.credits) {
    // Monthly credit limit reached.
    // Do not retry until next month or you upgrade your plan.
  } else {
    // Per-minute rate limit reached.
    // Implement a backoff strategy and retry.
  }
}

Consulte la sección «Errores » para ver la lista completa de códigos de estado.

Errores comunes#

• Jornadas intensas sin dormir. A para bucle sin esperar El intervalo entre solicitudes agotará las 60 llamadas en milisegundos y provocará un bloqueo.
• Paralelización sin un limitador compartido. Dos trabajadores que procesan 40 por minuto cada uno activarán el límite, aunque cada uno parezca «seguro».
• Volver a intentarlo 403 / 404 como si fueran límites de velocidad. Eso significa «acceso denegado» o «ruta incorrecta»; no funcionarán a menos que se modifique la solicitud o la cuenta.
• Encuesta /créditos para detectar la velocidad limitante. Ese punto final cuenta para el límite de rate (y consume un crédito). Fíjate en el 429 en su lugar.