youtube-transcript-api Errors Explained: IpBlocked, RequestBlocked and More

The library defines 17 error classes. Fourteen can be raised, and the three cookie classes (CookieError, CookieInvalid, CookiePathInvalid) are never raised anywhere in version 1.2.4. The fourteen:

These come from the library's source as follows. IpBlocked is raised when YouTube answers with HTTP 429, or returns a page containing a reCAPTCHA form. RequestBlocked is raised when YouTube asks for a sign-in because it suspects a bot. YouTubeRequestFailed covers any other HTTP error status, such as a 403 or a 5xx. YouTubeDataUnparsable means the page was fetched but did not contain what the library looks for, and was not the reCAPTCHA page. FailedToCreateConsentCookie means YouTube showed its cookie consent page and the library could not get past it, which can happen in some regions.

The library's own message for the first two lists the usual causes: too many requests from one IP, or requests coming from a cloud provider such as AWS, Google Cloud or Azure.

What helps, roughly from least to most effort:

• Back off. Wait, then retry slowly, with a cap. Do not loop.
• Cache what you fetch so each video is requested once.
• Run from a different network. A home or office connection is treated differently from a server.
• Send the requests through a proxy provider. The library supports proxy configuration, and its documentation recommends rotating residential proxies for IP bans.

• TranscriptsDisabled: the video data has no caption tracks at all. If "Show transcript" is missing in a browser too, there is nothing for any tool to fetch, and your only route to text is speech-to-text on the audio.
• VideoUnavailable: YouTube says the video is unavailable. It was removed, made private, blocked in a region, or the ID is wrong. yt-dlp prints This video is unavailable for the same ID.
• VideoUnplayable: YouTube will not play it, with its own reason. Live streams that are not archived and premieres that have not started are the common cases. Wait for the stream to end.
• AgeRestricted: YouTube only serves the video to signed-in users. yt-dlp prints Sign in to confirm your age and points to its cookie options. Automated use of an account can be restricted by YouTube, so treat these videos as unavailable unless you have a good reason not to.

Record these as normal answers and move on. A retry cannot change the result.

• NoTranscriptFound: none of the language codes you passed exist on the video. The error text lists what does. Codes must match exactly, so a request for es misses a track coded es-ES, and yt-dlp behaves the same way. Pass several codes in order of preference, or call list(video_id) and pick.
• InvalidVideoId: you passed a URL. The library wants the 11-character ID, so call fetch("jNQXAC9IVRw"), not fetch("https://...").
• NotTranslatable and TranslationLanguageNotAvailable: you asked for a machine translation that does not exist. Some tracks offer no translation languages at all (the first video ever uploaded to YouTube is one), and others offer a list, such as 18 languages on a popular math channel's video. Check is_translatable and translation_languages first.

PoTokenRequired appears when a caption track URL asks for a proof-of-origin token the library does not produce. Users report it for some videos, and the library asks you to open an issue, so check its tracker for the current state. The three cookie errors are left over from the 0.x versions, when cookies could be used to sign in. They are defined but never raised in 1.2.4, so code that catches them does nothing.

One small function that turns an exception into a decision keeps retry logic in one place. This one was run against every error class listed above:

from youtube_transcript_api import (
    AgeRestricted,
    InvalidVideoId,
    NoTranscriptFound,
    NotTranslatable,
    RequestBlocked,  # IpBlocked is a subclass, so this catches both
    TranscriptsDisabled,
    TranslationLanguageNotAvailable,
    VideoUnavailable,
    VideoUnplayable,
)


def classify(exc: Exception) -> str:
    if isinstance(exc, RequestBlocked):
        return "blocked"  # about your network: back off, change network, do not loop
    if isinstance(exc, (TranscriptsDisabled, VideoUnavailable, VideoUnplayable, AgeRestricted)):
        return "nothing_to_fetch"  # record it and move on
    if isinstance(exc, (NoTranscriptFound, InvalidVideoId, NotTranslatable, TranslationLanguageNotAvailable)):
        return "bad_request"  # fix the language code or the video ID
    return "other"  # read the message: YouTubeRequestFailed, PoTokenRequired, ...

Retry only blocked, with exponential back-off and a limit. Log the rest and continue.

Everything above works with free tools, and for a handful of videos from your own machine you probably need nothing else. The network errors are what hurt once code runs on a server. At that point you can run proxies yourself, or call a hosted transcript service so the blocked address is not yours. Several exist, including Supadata, TranscriptAPI, youtube-transcript.io and ours, GetYouTubeTranscript. We compare them without ranking in the transcript tools roundup and list our own error codes in the API troubleshooting checklist.

If we got anything here wrong, or a tool's maintainers see it differently, tell us in the repository and we will correct it.