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

これらはよく混同される2つの異なる制約です:

• クォータ - より長い時間枠（例: 1日）にわたって許可される総リクエスト数。使い切ると、時にはリセットまで何時間も待つ必要があります。
• レート制限 - より短い時間枠（例: 1分）ごとに許可されるリクエスト数。これに達しても、数秒から数分待つだけで済み、何時間も待つ必要はありません。

内部的には、ほとんどのAPIはトークンバケット（一定のペースでリクエスト「トークン」が蓄積され、リクエストごとに1つ消費する方式で、短時間のバーストを許容する）または固定／スライディングウィンドウカウンター（暦上の1分あたりのハードキャップで、境界でリセットされる方式）のいずれかでレート制限を実装しています。どちらの方式を採用しているかによって、トラフィックがどれだけバースト的であっても安全かが変わります - トークンバケットは固定ウィンドウよりも短時間のスパイクをうまく許容します。

429 Too Many Requestsは特定プロバイダー独自の慣習ではなく、標準的なHTTPステータスコードとしてRFC 6585（2012年4月）で正式に定義されています。RFC 9110によれば、準拠したサーバーは429（または503）レスポンスに次の2つの形式のいずれかでRetry-Afterヘッダーを付与してもよいとされています:

• 秒数指定形式 - 整数、例: Retry-After: 120は120秒待つことを意味します。
• HTTP日時形式 - 絶対的なタイムスタンプ、例: Retry-After: Wed, 21 Oct 2026 07:28:00 GMT。

このヘッダーが存在する場合、それは権威的な情報です - サーバーは次にいつリクエストを受け付けるかを正確に伝えています。その上に独自の指数バックオフを重ねないでください。それは回復をさらに遅らせるだけです。ヘッダーが存在しない場合にのみバックオフにフォールバックしてください。

正しい処理順序は、まずRetry-Afterを確認し、それが欠落している場合にのみジッター付きの指数バックオフにフォールバックすることです。ジッター（待機時間をわずかにランダム化すること）が重要なのは、多数のクライアントが同時に制限にぶつかり、すべてが同一のスケジュールで再試行すると、それらが同期して即座に同じ制限に再びぶつかる「サンダリングハード」を引き起こすためです。

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

1分あたりのリクエスト上限と、処理中（in-flight）の並行数の上限は同じものではありません。Promise.allで50個のリクエストを同時に発火させると、その分の合計が予算内に十分収まっていても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無料クレジットで始めてください。