youtube-transcript-api errors

youtube-transcript-api errors and how to fix them

Every exception the youtube-transcript-api Python library raises, what each one means, and the fix, from IP blocks on cloud servers to missing captions.

Running this on a server? TranscriptFetch returns the same transcript from any IP, no proxies. Try it free →

youtube-transcript-api is the most widely used Python library for YouTube transcripts. When it cannot return a transcript it raises a specific exception, and the exception name tells you whether the problem is your code, the video, or where your code runs.

Written against version 1.2.4 of the library. The exception names and messages below are copied from its source.

Find your error

ExceptionWhat it means
RequestBlockedYouTube is refusing requests from your IP: usually a cloud server or too many requests.
IpBlockedThe same block, detected as an HTTP 429 or a CAPTCHA page.
TranscriptsDisabledSubtitles are disabled for this video.
NoTranscriptFoundThe video has transcripts, but none in the language codes you asked for.
VideoUnavailableThe video is no longer available: removed, private, or the ID is wrong.
InvalidVideoIdYou passed a URL where the library expects a video ID.
AgeRestrictedThe video is age-restricted, and the library cannot fetch it without signing in.
PoTokenRequiredYouTube asked for a proof-of-origin token the library cannot provide.
VideoUnplayableYouTube reports the video as unplayable, with a reason (region lock, members only and similar).
YouTubeRequestFailedThe HTTP request to YouTube itself failed; the message carries the reason.
NotTranslatableThe transcript you picked cannot be translated.
TranslationLanguageNotAvailableThe translation language you asked for is not offered.
FailedToCreateConsentCookieThe library could not accept YouTube's cookie consent page (common on EU servers).
YouTubeDataUnparsableYouTube's response changed shape; usually fixed by upgrading the library.
CookieError, CookiePathInvalid, CookieInvalidProblems loading the cookie file used to sign in.
TooManyRequestsVersions before 1.0: the same IP block, now raised as IpBlocked.

Errors about where your code runs

RequestBlocked, IpBlocked and PoTokenRequired say nothing about your code. They appear when YouTube decides the request looks automated: almost always on cloud servers (AWS, Google Cloud, Azure and most hosting), or after many requests from one IP. The same script usually works on a laptop. How to fix RequestBlocked and IpBlocked.

Catching them

Every exception above except the cookie errors inherits from CouldNotRetrieveTranscript, so one except covers them:

python
from youtube_transcript_api import (
    CouldNotRetrieveTranscript,
    RequestBlocked,
    YouTubeTranscriptApi,
)

try:
    transcript = YouTubeTranscriptApi().fetch(video_id)
except RequestBlocked:
    ...  # where you run: see the RequestBlocked page
except CouldNotRetrieveTranscript as e:
    print(type(e).__name__, e)  # about the video itself

Catch RequestBlocked before CouldNotRetrieveTranscript: it is the one you can do something about, and IpBlocked is a subclass of it.

When the library is not enough

The library reads YouTube directly from wherever your code runs, which is why server deployments hit IP blocks. TranscriptFetch is a hosted API (our product) that fetches from its own network, so the same request works from any server. It returns the transcript as text and timestamped segments, also covers TikTok and Instagram, and transcribes the audio with AI when a video has no captions. 50 free credits a month, no card.

Need transcripts that work from a server?

TranscriptFetch fetches YouTube, TikTok and Instagram transcripts from its own network, with AI transcription when a video has no captions. Free credits every month, no card.

Get a free API keySee the API