YouTube-Transkript-API funktioniert nicht? Diagnose-Checkliste
Jeder echte Grund, warum eine Transkript-Anfrage fehlschlägt, basierend auf den meistdiskutierten Issues der Open-Source-Community selbst - keine Vermutungen - plus der genaue Fehlercode und die Lösung für jeden.
Diagnose-Checkliste
Gleiche deinen Fehlercode (oder die Form deiner Antwort) mit der Tabelle unten ab.
| Code | Was es bedeutet | Was zu tun ist |
|---|---|---|
MISSING_URL / INVALID_URL · 400 | Der v-Parameter fehlt oder ist keine Video-ID/URL, die YouTube erkennt. | Übergib eine gültige 11-stellige Video-ID oder eine vollständige youtube.com/watch?v=...-URL. |
VIDEO_UNAVAILABLE · 404 | Das Video ist privat, gelöscht oder regional gesperrt - aus Sicht des Servers existiert es nicht. | Prüfe zuerst, ob das Video in einem normalen Browser lädt. Falls nicht, gibt es nichts, was eine API abrufen könnte. |
TRANSCRIPT_DISABLED · 404 | Bedeutet meistens, dass der Uploader Untertitel deaktiviert hat - aber Regionssperren und IP-Blocks können genau denselben Fehler erzeugen. | Siehe den Hinweis unten, bevor du davon ausgehst, dass es dauerhaft ist. |
LANGUAGE_NOT_AVAILABLE · 404 | Das Video hat Untertitel, nur nicht in der angeforderten Sprache. | Lass den Sprachparameter weg, um zu bekommen, was verfügbar ist, oder prüfe zuerst die eigene Untertitelliste des Videos. |
TRANSCRIPT_NOT_FOUND · 404 | Es existiert kein Transkript in irgendeiner Sprache für dieses Video. | Wie bei deaktivierten Untertiteln - nichts abzurufen. Nicht jedes Video hat eins. |
RATE_LIMITED · 429 | Dein API-Schlüssel hat mehr Anfragen gestellt, als das Minutenlimit deines Plans erlaubt. | Drosseln und erneut versuchen, oder auf ein höheres Rate-Limit upgraden. |
UPSTREAM_* · 429/503/504 | Ein vorübergehendes Problem direkt bei YouTube, nicht bei deinem Schlüssel oder deiner Anfrage. | Nach kurzer Wartezeit gefahrlos erneut versuchbar - genau die Art von Fehler, die eine gehostete API für dich abfängt. |
"Untertitel deaktiviert" heißt nicht immer deaktiviert
Das meistdiskutierte Issue in der gesamten Geschichte des Open-Source-youtube-transcript-api (187 Kommentare) ist ein Skript, das "TranscriptsDisabled" für ein Video wirft, das gar nicht wirklich deaktiviert ist - es spielt Untertitel in einem normalen Browser problemlos ab. Drei verschiedene echte Ursachen erzeugen einen fast identischen Fehler:
- Wirklich deaktiviert - der Uploader hat Untertitel abgeschaltet. Nichts abzurufen, in keiner Sprache.
- Regional gesperrt - das Video oder seine Untertitel sind aus dem Land deines Servers nicht verfügbar, funktionieren aber von einem Browser in einer anderen Region.
- IP-blockiert - YouTube liefert einen generischen statt einen spezifischen Fehler, und die echte Ursache ist das Cloud-Hosting-Problem weiter unten.
Ein roher XML-Parse-Fehler ("no element found", "line 1, column 0") statt einer sauberen Exception gehört zur selben Problemfamilie - ein leerer Antwortkörper, meist durch denselben IP-Block oder PoToken-Grund unten, kein Bug im Parsing-Code selbst.
Blockiert auf AWS, GCP, Azure oder einem VPS?
Wenn ein Skript auf dem Laptop einwandfrei läuft und dann genau in dem Moment fehlschlägt, in dem es auf einem Cloud-Server bereitgestellt wird, liegt es fast immer daran: Der Untertitel-Endpoint von YouTube blockiert ganze Rechenzentrums-IP-Bereiche, nicht nur einzelne missbräuchliche IPs. Der IP-Bereich jedes großen Cloud-Anbieters wird irgendwann davon getroffen, weil tausende unabhängige Skripte dieselben Adressbereiche teilen.
Could not retrieve a transcript for the video https://www.youtube.com/watch?v=...!
This is most likely caused by:
YouTube is blocking requests from your IP.Realistische Wege, das zu umgehen, ungefähr nach Aufwand geordnet:
- Anfragen über einen Residential- oder Mobile-Proxy-Pool leiten - funktioniert manchmal, aber Berichte, dass sogar bezahlte rotierende Residential-Setups weiterhin fehlschlagen, häufen sich. Keine dauerhafte Lösung.
- Zwischen mehreren Cloud-Anbietern oder Regionen wechseln - verschafft Zeit, bis auch diese Bereiche markiert werden.
- Aggressiv cachen, um dieselben Videos nicht erneut abzurufen - reduziert, wie oft der Block getroffen wird, beseitigt ihn aber nicht.
- Eine gehostete API nutzen, die diese Infrastruktur bereits betreibt - das Problem wandert von 'deinem Projekt' zu 'jemandem, dessen eigentlicher Job es ist, das am Laufen zu halten'.
Genau diese Lücke füllt unsere eigene YouTube-Transkript-API - keine andere Bibliothek, sondern Infrastruktur, die schon genau für dieses Problem gebaut wurde.
Bekommst du PoTokenRequired?
Ein neuerer Fehlerfall: Der Untertitel-Endpoint von YouTube verlangt zunehmend ein zur Laufzeit von seinem eigenen Player-JavaScript erzeugtes Proof-of-Origin-Token - kein Cookie, keine IP-Reputationsprüfung, ein kryptografischer Wert. Eine einfache HTTP-Anfrage hat keine Möglichkeit, so etwas zu erzeugen.
Das echte technische Detail steht in jdepoix/youtube-transcript-api#592 - Stand dieses Berichts gibt es keine dokumentierte Umgehung in der Open-Source-Bibliothek.
Genau diese Art von Problem soll eine gehostete API abfangen - ein Endpoint aufrufen und ein Transkript oder einen klaren Fehler zurückbekommen, ohne die Token-Generierung selbst lösen zu müssen.
Was unsere eigene API bei jedem Fehler zurückgibt
Wer schon unsere API nutzt und nach dem genauen Fehler statt nur dem HTTP-Status verzweigen will: Jeder Fehler kommt mit einem stabilen `code`-Feld zurück:
curl "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
-H "Authorization: Bearer sk_live_..."
# A failure looks like:
# { "success": false, "code": "TRANSCRIPT_DISABLED", "message": "Transcripts are disabled for this video." }Die vollständige Parameter-Referenz und alle Statuscodes stehen in der API-Dokumentation.
Häufige Fehler der YouTube-Transkript-API
Warum bekomme ich 'YouTube is blocking requests from your IP'?
Du rufst den Untertitel-Endpoint von YouTube von einer Cloud-/Rechenzentrums-IP-Adresse aus auf (AWS, GCP, Azure, ein VPS...), und YouTube blockiert diese Bereiche aggressiver als Heim-/Residential-IPs. Meist ist es nicht persönlich - es ist der gesamte IP-Bereich, geteilt mit tausenden anderen Skripten.
Warum funktioniert mein Skript lokal, schlägt aber nach dem Deployment fehl?
Dein Laptop hat eine Residential-IP; dein Server hat eine Rechenzentrums-IP. Gleicher Code, andere Netzwerkreputation - die mit Abstand häufigste Ursache für "funktioniert hier, schlägt dort fehl" bei jedem, der eine YouTube-Transkript-Bibliothek selbst hostet.
Warum stellt sich 'Untertitel deaktiviert' manchmal als falsch heraus?
Weil YouTube nicht immer einen konkreten Grund zurückgibt - eine Regionssperre oder ein IP-Block können denselben generischen Fehler erzeugen wie ein wirklich deaktiviertes Video. Prüfe, ob das Video in einem normalen Browser über ein anderes Netzwerk Untertitel abspielt, bevor du von dauerhafter Nichtverfügbarkeit ausgehst.
Was ist PoTokenRequired?
YouTube verlangt ein zur Laufzeit vom echten Player-JavaScript erzeugtes Proof-of-Origin-Token, keinen statischen Wert, den man hart codieren oder einmal extrahieren kann. Einfache HTTP-Anfragen - und die meisten Scraping-Bibliotheken - haben keine Möglichkeit, eines zu erzeugen, weshalb es aktuell keine dokumentierte Umgehung in der Open-Source-Bibliothek gibt.
Warum gibt es kein Transkript in der gewünschten Sprache?
Das Video hat Untertitel, nur nicht in dieser Sprache. Frage ohne Sprachparameter an, um zu bekommen, was verfügbar ist, oder prüfe zuerst, welche Sprachen existieren.
Wie vermeide ich Rate-Limits?
Es gibt zwei unterschiedliche Limits: die Anfragen-pro-Minute-Obergrenze deines eigenen Plans (auf ein höheres upgraden) und YouTubes eigene Upstream-Limits (nach kurzer Wartezeit gefahrlos erneut versuchbar - eine gehostete API fängt das meiste davon für dich ab).