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

Das sind zwei unterschiedliche Beschränkungen, die häufig verwechselt werden:

• Kontingent – Gesamtzahl erlaubter Anfragen über ein längeres Fenster (z. B. einen Tag). Ist es aufgebraucht, müssen Sie auf ein Reset warten, das manchmal viele Stunden entfernt ist.
• Rate-Limit – Anzahl erlaubter Anfragen pro kurzem Fenster (z. B. einer Minute). Wird es erreicht, bedeutet das ein paar Sekunden bis eine Minute Verlangsamung, nicht Stunden.

Im Hintergrund implementieren die meisten APIs Rate-Limiting entweder über einen Token-Bucket (Sie sammeln in stetigem Tempo Anfrage-"Tokens" an und verbrauchen einen pro Anfrage, was kurze Bursts erlaubt) oder einen Fixed-/Sliding-Window-Zähler (eine feste Obergrenze pro Kalenderminute, die an der Grenze zurückgesetzt wird). Welche eine bestimmte API verwendet, bestimmt, wie ausbrechend Ihr Traffic sicher sein kann – ein Token-Bucket verträgt einen kurzen Spitzenwert besser als ein festes Fenster.

429 Too Many Requests ist keine anbieterspezifische Folklore – er wurde formal in RFC 6585 (April 2012) als Standard-HTTP-Statuscode definiert. Gemäß RFC 9110 kann ein konformer Server einer 429- (oder 503-)Antwort einen Retry-After-Header in einer von zwei Formen anhängen:

• Delay-Seconds-Form – eine Ganzzahl, z. B. Retry-After: 120, bedeutet 120 Sekunden warten.
• HTTP-Date-Form – ein absoluter Zeitstempel, z. B. Retry-After: Wed, 21 Oct 2026 07:28:00 GMT.

Ist er vorhanden, ist dieser Header maßgeblich – der Server sagt Ihnen genau, wann er wieder Anfragen akzeptiert. Legen Sie kein eigenes exponentielles Backoff darüber – das verzögert Ihre Erholung nur weiter. Greifen Sie nur dann auf Backoff zurück, wenn der Header fehlt.

Die richtige Reihenfolge: zuerst auf Retry-After prüfen, und nur auf exponentielles Backoff mit Jitter zurückgreifen, wenn er fehlt. Jitter (das leichte Zufälligmachen der Wartezeit) ist wichtig, weil viele Clients, die ein Limit gleichzeitig treffen und alle nach einem identischen Zeitplan erneut versuchen, sich synchronisieren und einen "Thundering Herd" erzeugen, der dasselbe Limit sofort erneut auslöst.

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

Eine Obergrenze für Anfragen pro Minute und eine Obergrenze für gleichzeitig laufende Anfragen sind nicht dasselbe. Das gleichzeitige Abfeuern von 50 Anfragen mit Promise.all kann einen 429 auslösen, selbst wenn Ihr Gesamtwert für die Minute deutlich unter dem Budget liegt, weil der Server (oder ein vorgeschalteter Proxy) auch die Zahl gleichzeitiger Verbindungen begrenzen kann. Begrenzen Sie bei der Stapelverarbeitung vieler Videos die Nebenläufigkeit unabhängig von Ihrem Rate-Limit-Backoff:

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

Für anhaltend hohes Volumen erhöht ein Plan-Upgrade die Obergrenze für Anfragen/Min. direkt – siehe Preise in der API-Dokumentation, oder starten Sie mit 100 kostenlosen Credits über das Dashboard.