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

Essas são duas restrições diferentes que frequentemente se confundem:

• Cota - total de requisições permitidas em uma janela mais longa (por exemplo, um dia). Esgotá-la significa esperar por um reset, às vezes horas depois.
• Limite de taxa - requisições permitidas por uma janela curta (por exemplo, um minuto). Atingi-lo significa desacelerar por segundos a um minuto, não horas.

Por baixo dos panos, a maioria das APIs implementa o limite de taxa com um token bucket (você acumula "tokens" de requisição a uma taxa constante e gasta um por requisição, permitindo pequenas explosões) ou um contador de janela fixa/deslizante (um teto rígido por minuto do relógio, reiniciando no limite). Qual deles uma dada API usa muda o quão explosivo seu tráfego pode ser com segurança - um token bucket tolera um pico curto melhor do que uma janela fixa.

429 Too Many Requests não é folclore específico de provedor - foi formalmente definido na RFC 6585 (abril de 2012) como um código de status HTTP padrão. Segundo a RFC 9110, um servidor compatível pode anexar um cabeçalho Retry-After a uma resposta 429 (ou 503), em uma de duas formas:

• Forma delay-seconds - um número inteiro, por exemplo Retry-After: 120, significando esperar 120 segundos.
• Forma HTTP-date - um timestamp absoluto, por exemplo Retry-After: Wed, 21 Oct 2026 07:28:00 GMT.

Quando presente, este cabeçalho é a autoridade - o servidor está te dizendo exatamente quando voltará a aceitar requisições. Não sobreponha seu próprio backoff exponencial a ele; isso só atrasa ainda mais sua recuperação. Só recorra ao backoff quando o cabeçalho estiver ausente.

A ordem correta de operações: verifique Retry-After primeiro, e só recorra ao backoff exponencial com jitter se ele estiver ausente. O jitter (aleatorizar levemente a espera) importa porque, quando muitos clientes atingem um limite simultaneamente e todos tentam de novo no mesmo cronograma, eles se sincronizam e criam um "efeito manada" que reativa imediatamente o mesmo limite.

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")

Um teto de requisições por minuto e um teto de concorrência simultânea não são a mesma coisa. Disparar 50 requisições simultaneamente com Promise.all pode acionar um 429 mesmo que seu total do minuto esteja bem dentro do orçamento, porque o servidor (ou um proxy na frente dele) também pode limitar conexões simultâneas. Ao processar muitos vídeos em lote, limite a concorrência independentemente do seu backoff de limite de taxa:

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 sustentados de alto volume, fazer upgrade de plano eleva diretamente o teto de req/min - veja preços na documentação da API, ou comece com 100 créditos grátis no painel.