YouTube Transcript API Rate Limit: What It Is and How to Handle 429s

Son dos restricciones distintas que suelen confundirse:

• Cuota - el total de solicitudes permitidas en una ventana más larga (por ejemplo, un día). Agotarla significa esperar un restablecimiento, a veces a muchas horas de distancia.
• Límite de tasa - las solicitudes permitidas por ventana corta (por ejemplo, un minuto). Alcanzarlo significa ir más despacio durante segundos o un minuto, no horas.

Por debajo, la mayoría de las APIs implementan el límite de tasa con un token bucket (acumulas "tokens" de solicitud a un ritmo constante y gastas uno por solicitud, lo que permite ráfagas cortas) o un contador de ventana fija/deslizante (un tope estricto por minuto de calendario, que se reinicia en el límite). Cuál de los dos use una API determinada cambia qué tan intermitente puede ser tu tráfico de forma segura: un token bucket tolera mejor un pico corto que una ventana fija.

429 Too Many Requests no es folclore específico de un proveedor: se definió formalmente en la RFC 6585 (abril de 2012) como un código de estado HTTP estándar. Según la RFC 9110, un servidor conforme puede adjuntar un encabezado Retry-After a una respuesta 429 (o 503), en una de estas dos formas:

• Forma de segundos de retraso - un número entero, por ejemplo Retry-After: 120, que significa esperar 120 segundos.
• Forma de fecha HTTP - una marca de tiempo absoluta, por ejemplo Retry-After: Wed, 21 Oct 2026 07:28:00 GMT.

Cuando está presente, este encabezado es autoritativo: el servidor te dice exactamente cuándo volverá a aceptar solicitudes. No agregues tu propio retroceso exponencial encima; eso solo retrasa más tu recuperación. Recurre al retroceso solo cuando el encabezado esté ausente.

El orden correcto de operaciones: primero verifica si existe Retry-After, y solo recurre al retroceso exponencial con jitter si falta. El jitter (aleatorizar ligeramente la espera) importa porque cuando muchos clientes alcanzan un límite simultáneamente y todos reintentan con el mismo cronograma, se sincronizan y crean una "estampida" que vuelve a activar de inmediato el mismo límite.

Node.js:

async function getTranscriptWithRetry(videoId, apiKey, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(
      `https://getyoutubetranscript.com/api/v1/transcript?v=${videoId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    if (res.status !== 429) return res.json();

    const retryAfter = res.headers.get('retry-after');
    const waitMs = retryAfter
      ? Number(retryAfter) * 1000
      : 500 * 2 ** attempt + Math.random() * 250; // exponential backoff + jitter
    await new Promise((r) => setTimeout(r, waitMs));
  }
  throw new Error('Rate limited after retries');
}

Python:

import os, time, random, requests

def get_transcript_with_retry(video_id, api_key, max_retries=4):
    url = "https://getyoutubetranscript.com/api/v1/transcript"
    for attempt in range(max_retries + 1):
        res = requests.get(url, params={"v": video_id}, headers={"Authorization": f"Bearer {api_key}"})
        if res.status_code != 429:
            return res.json()

        retry_after = res.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else (0.5 * 2 ** attempt + random.uniform(0, 0.25))
        time.sleep(wait)
    raise RuntimeError("Rate limited after retries")

Un límite de solicitudes por minuto y un límite de concurrencia simultánea no son lo mismo. Disparar 50 solicitudes al mismo tiempo con Promise.all puede activar un 429 incluso si tu total del minuto está muy por debajo del presupuesto, porque el servidor (o un proxy delante de él) también puede limitar las conexiones simultáneas. Al procesar muchos videos por lotes, limita la concurrencia de forma independiente a tu retroceso por límite de tasa:

import pLimit from 'p-limit';

const limit = pLimit(5); // at most 5 requests in flight at once
const results = await Promise.all(
  videoIds.map((id) => limit(() => getTranscriptWithRetry(id, apiKey)))
);

Para lotes sostenidos de alto volumen, subir de nivel de plan aumenta directamente el límite de solicitudes por minuto; consulta los precios en la documentación de la API, o empieza con 100 créditos gratis desde el panel.