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

Đây là hai ràng buộc khác nhau nhưng thường bị nhầm lẫn:

• Quota - tổng số request được phép trong một khoảng thời gian dài hơn (ví dụ một ngày). Dùng hết nghĩa là phải chờ reset, đôi khi cách nhiều giờ.
• Rate limit - số request được phép trong một khoảng thời gian ngắn (ví dụ một phút). Chạm giới hạn nghĩa là chậm lại vài giây đến một phút, không phải hàng giờ.

Bên dưới lớp vỏ, hầu hết API thực thi rate limit bằng một trong hai cách: token bucket (bạn tích lũy "token" request theo một tốc độ ổn định và tiêu một token mỗi request, cho phép các đợt bùng nổ ngắn) hoặc một bộ đếm cửa sổ cố định/trượt (một trần cứng cho mỗi phút lịch, reset ở ranh giới). Cách nào được một API sử dụng sẽ ảnh hưởng đến mức lưu lượng bùng nổ mà bạn có thể an toàn gửi đi - một token bucket chịu được một đợt tăng đột biến ngắn tốt hơn một cửa sổ cố định.

429 Too Many Requests không phải là quy ước riêng của nhà cung cấp nào - nó được định nghĩa chính thức trong RFC 6585 (tháng 4 năm 2012) như một mã trạng thái HTTP chuẩn. Theo RFC 9110, một server tuân thủ có thể đính kèm header Retry-After vào một response 429 (hoặc 503), theo một trong hai dạng:

• Dạng số giây trễ - một số nguyên, ví dụ Retry-After: 120, nghĩa là chờ 120 giây.
• Dạng HTTP-date - một mốc thời gian tuyệt đối, ví dụ Retry-After: Wed, 21 Oct 2026 07:28:00 GMT.

Khi có mặt, header này là căn cứ chính thức - server đang cho bạn biết chính xác khi nào nó sẽ chấp nhận request trở lại. Đừng chồng thêm exponential backoff của riêng bạn lên trên nó; điều đó chỉ trì hoãn thêm việc phục hồi. Chỉ dùng backoff khi header này vắng mặt.

Thứ tự thao tác đúng: kiểm tra Retry-After trước, và chỉ chuyển sang exponential backoff kèm jitter nếu thiếu header đó. Jitter (ngẫu nhiên hóa nhẹ thời gian chờ) quan trọng vì khi nhiều client cùng chạm giới hạn một lúc và tất cả thử lại theo cùng một lịch trình, chúng đồng bộ hóa và tạo ra một "đàn thác" ngay lập tức chạm lại cùng giới hạn đó.

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

Một trần request-per-minute và một trần đồng thời (in-flight) không phải là cùng một thứ. Bắn 50 request cùng lúc bằng Promise.all có thể gây ra một 429 dù tổng số của bạn trong phút vẫn còn trong ngân sách, vì server (hoặc một proxy phía trước nó) cũng có thể giới hạn số kết nối đồng thời. Khi xử lý hàng loạt nhiều video, hãy giới hạn mức đồng thời độc lập với backoff rate-limit của bạn:

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

Với các lô khối lượng lớn kéo dài, nâng cấp gói sẽ trực tiếp nâng trần req/phút - xem bảng giá trong tài liệu API, hoặc bắt đầu với 100 tín dụng miễn phí từ dashboard.