What the error means
youtube-transcript-api is a popular open-source Python library that reads a video’s caption track. It talks to YouTube directly from whatever machine runs your code. When YouTube refuses those requests, current releases (1.2.5 at the time of writing) raise RequestBlocked or IpBlocked.
The library’s README gives the reason plainly: YouTube has started blocking most IP addresses known to belong to cloud providers such as AWS, Google Cloud Platform and Azure. It adds that the same can happen to a self-hosted machine that sends too many requests. The block is about where the request comes from, not about your code, so changing the code or upgrading the library does not fix it.
Quick test: run the same script on your own computer with the same video ID. If it works there and fails on the server, the server’s IP address is blocked.
Fix 1: Run it from a residential connection
For a one-off job, such as pulling transcripts for a research project, run the script on your own computer. A home or office connection is rarely blocked at low volume. This costs nothing, but it is not a production setup: your laptop has to be on, and a home IP can still be blocked if you send a lot of requests quickly.
Fix 2: Rotating residential proxies
The README’s recommended fix for servers is a proxy, and it is specific about the kind: rotating residential proxies, because YouTube bans static proxies after extended use. It has built-in support for Webshare and says to buy a Residential package, not “Proxy Server” or “Static Residential”.
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.proxies import WebshareProxyConfig
ytt_api = YouTubeTranscriptApi(
proxy_config=WebshareProxyConfig(
proxy_username="<proxy-username>",
proxy_password="<proxy-password>",
)
)
ytt_api.fetch(video_id)Any other HTTP, HTTPS or SOCKS proxy works through GenericProxyConfig:
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.proxies import GenericProxyConfig
ytt_api = YouTubeTranscriptApi(
proxy_config=GenericProxyConfig(
http_url="http://<user>:<password>@<proxy-host>:<port>",
https_url="http://<user>:<password>@<proxy-host>:<port>",
)
)Two things to plan for. Residential proxy plans are usually billed by bandwidth, so cost grows with volume. And the README itself warns that a proxy does not guarantee you will not be blocked, because YouTube can block the proxy’s IP as well. Log failures and retry them later rather than in a tight loop.
Fix 3: Send fewer requests
A block is more likely when one IP fetches many transcripts in a short time. Whatever else you do, store every transcript you have already fetched and never request the same video twice. Spread large jobs out over time, and stop the job on the first block instead of retrying hundreds of videos against an IP that is already refused.
Fix 4: Use a hosted transcript API
A hosted API moves the YouTube side of the problem off your server. Your code calls an ordinary HTTPS endpoint, and the provider fetches the captions from its own infrastructure, so it no longer matters that your server runs on AWS. The TubeToTranscript YouTube transcript API works this way:
import requests
res = requests.post(
"https://www.tubetotranscript.com/api/v1/transcript",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"url": "https://www.youtube.com/watch?v=VIDEO_ID", "language": "en"},
)
data = res.json()
if res.ok:
for seg in data["transcript"]:
print(f"[{seg['start']:.0f}s] {seg['text']}")
else:
print(res.status_code, data.get("code"), data.get("error"))A new API key includes 10 free requests to test with. After that, a one-time pack adds 250 requests for $1.50, or Pro includes 1,500 a month for $4.49. Only successful requests count. See the YouTube transcript API JSON guide for cURL and JavaScript versions, and the cheapest YouTube transcript API comparison for other hosted options and their prices.
Which fix to choose
| Fix | Cost | Good for | Watch out for |
|---|---|---|---|
| Run locally | Free | One-off jobs, a few hundred videos | Not a server setup; home IPs can be blocked too |
| Rotating residential proxy | Proxy plan, usually by bandwidth | Keeping the open-source library in production | Proxies can be blocked; you maintain retries |
| Fewer requests and caching | Free | Every setup | Does not unblock an IP that is already blocked |
| Hosted API | Per request | Servers, serverless functions, AI agents | Another service to depend on; captions must exist |
The YouTube transcript API alternatives page compares the open-source library, the official YouTube Data API and hosted services in more detail.
Related tools and guides
- Free YouTube transcript API is a hosted option with 10 trial requests.
- YouTube transcript API alternatives compares the library, the official Data API and hosted services.
- API documentation lists every endpoint and error code.