youtube-transcript-api blocked: what the errors mean and how to fix them

The exact errors the library raises

Every failure in youtube-transcript-api subclasses CouldNotRetrieveTranscript, whose message is Could not retrieve a transcript for the video {url}! followed by the specific cause. The cause line is the part that matters. Names and messages below are from the library's _errors.py.

Two more show up less often. VideoUnplayable carries YouTube's own reason string. PoTokenRequired means YouTube asked for a proof-of-origin token that the library cannot mint, which is another way of saying the request looked automated. Treat it like a block.

Why it works on your laptop and fails on the server

The library reads the caption track through the same watch page your browser loads. YouTube serves that page freely to residential addresses and refuses it to address ranges it associates with bots, which in practice means every cloud provider. Your laptop is on a home ISP. Your container is on AWS, GCP, Azure, Hetzner, Fly, Railway or Render. The code is identical; the address is not.

The README is explicit: YouTube "has started blocking most IPs that are known to belong to cloud providers ... which means you will most likely run into RequestBlocked or IpBlocked exceptions when deploying your code to any cloud solutions."

A second trap: curl from the server returning a 200 for the watch URL. That does not prove the caption endpoint is reachable; the block applies to the caption fetch, not the HTML shell. The false positive, and why the official Data API is not a way around it, is covered in why you cannot download captions you do not own.

A third: exits in the EU intermittently get the cookie-consent wall instead of the page, which the library reports as a failed request. It comes and goes per IP, so it reads as flakiness.

The fix: move the fetch to a hosted API

Keeping the library working on a server is possible, but it turns into its own project:

• Rotating residential proxies. Datacenter proxies get blocked the same way your server does.
• A pool pinned to one non-EU region, or the cookie-consent wall shows up as random failures.
• Retries through fresh exit IPs, capped. A retry through the same blocked address can't succeed.
• Health checks that fetch a real transcript, because a 200 on the watch page proves nothing.
• Metered bandwidth of about 377 KB per fetch, paid again for every failed attempt.
• Silent breakage whenever YouTube changes its pages, until a new library version ships.

TranscriptAPI already runs all of that. You send a video ID and get segments back in the same text / start / duration shape the library returns. Blocks are handled on our side, failed requests are refunded, and a video you have fetched before comes from cache for free.

One credit per transcript. You get 20 free credits at signup, then from $10 for 2,500, or $49 a month for 25,000 (see the pricing page). It can't read a video whose captions are turned off; nothing can. What goes away is the whole blocked class of failures. The full comparison is on the youtube-transcript-api alternative page.

How TranscriptAPI maps these failures

We run the same class of fetch, so we see the same exceptions. Each one is translated into a status code, an error name, a plain-language hint, and a retryable flag you can branch on without parsing prose. The credit is refunded in every case.

{
  "detail": "This video has captions turned off, so there is no transcript to fetch. Your credits have been refunded.",
  "error": "TranscriptsDisabled",
  "hint": "Retrying will not help — the uploader has disabled captions for this video.",
  "retryable": false,
  "credits_refunded": true
}

The rule for an automation is one line: 404 means skip, 5xx means retry with backoff. Status codes and the refund policy are documented in the API reference.

The same fetch, hosted

curl "https://api.transcriptapi.io/transcript?video_id=dQw4w9WgXcQ" \
  -H "Authorization: Bearer ta_..."

import requests

r = requests.get(
    "https://api.transcriptapi.io/transcript",
    params={"video_id": "dQw4w9WgXcQ"},
    headers={"Authorization": "Bearer ta_..."},
    timeout=60,
)
if r.status_code == 404:
    skip(r.json()["hint"])     # retryable: false
elif r.status_code >= 500:
    retry_later()               # refunded already
else:
    segments = r.json()["transcript"]

Porting an existing codebase, including the older get_transcript() form, is walked through in the migration guide.

Frequently asked questions