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

Это два разных ограничения, которые часто путают:

• Квота — общее число разрешённых запросов за более длинный период (например, за день). Исчерпание означает ожидание сброса, иногда через много часов.
• Лимит частоты запросов — число запросов, разрешённых за короткий период (например, за минуту). Достижение лимита означает замедление на секунды или минуту, а не часы.

Под капотом большинство API реализуют ограничение частоты запросов либо через token bucket (вы накапливаете «токены» запросов с постоянной скоростью и тратите по одному на запрос, что допускает короткие всплески), либо через счётчик с фиксированным/скользящим окном (жёсткий лимит на календарную минуту, сбрасываемый на границе). То, какой из вариантов использует конкретный API, влияет на то, насколько «взрывным» может безопасно быть ваш трафик — token bucket лучше переносит короткий всплеск, чем фиксированное окно.

429 Too Many Requests — это не частный фольклор конкретного провайдера: он был формально определён в RFC 6585 (апрель 2012) как стандартный код состояния HTTP. Согласно RFC 9110, соответствующий стандарту сервер может прикрепить заголовок Retry-After к ответу 429 (или 503) в одной из двух форм:

• Форма задержки в секундах — целое число, например Retry-After: 120, что означает подождать 120 секунд.
• Форма HTTP-даты — абсолютная метка времени, например Retry-After: Wed, 21 Oct 2026 07:28:00 GMT.

Если этот заголовок присутствует, он является авторитетным — сервер прямо говорит вам, когда он снова начнёт принимать запросы. Не накладывайте свой собственный экспоненциальный откат поверх него — это лишь дополнительно отсрочит восстановление. Прибегайте к откату только тогда, когда заголовок отсутствует.

Правильный порядок действий: сначала проверьте Retry-After, и только если он отсутствует, переходите к экспоненциальному откату со случайным разбросом. Разброс (небольшая рандомизация задержки) важен, потому что когда много клиентов одновременно упираются в лимит и все повторяют попытку по одинаковому расписанию, они синхронизируются и создают «эффект грозовой толпы» (thundering herd), который мгновенно повторно провоцирует тот же лимит.

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

Потолок запросов в минуту и потолок одновременных соединений — это не одно и то же. Одновременный запуск 50 запросов через Promise.all может спровоцировать 429, даже если ваш итог за минуту хорошо укладывается в бюджет, потому что сервер (или прокси перед ним) может также ограничивать число одновременных соединений. При пакетной обработке множества видео ограничивайте параллелизм отдельно от отката по лимиту частоты запросов:

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

Для устойчивых высокообъёмных пакетов повышение тарифа напрямую увеличивает потолок запросов в минуту — см. тарифы в документации API или начните с 100 бесплатных кредитов в панели управления.