When an item in a batch fails, it's almost always one of a small number of reasons. This is a reference list of the main ones, what's permanent versus worth a second attempt, and how to check a video before you submit it.
None of these are Scriptube-specific quirks — they're the same constraints anyone pulling data from YouTube runs into, whether through a tool or by hand.
Why this list exists
If you've only ever worked with a handful of videos, a failed item feels like a one-off glitch worth investigating individually. Once you're running batches of dozens or hundreds of videos — a full channel, a long-running playlist, a research corpus — a small percentage of failures becomes routine, and it's faster to recognize which bucket a failure falls into than to look up each one from scratch. That's what this list is for.
No captions exist
The video simply doesn't have any caption track — no creator-uploaded subtitles, and YouTube's automatic captioning hasn't produced one either. This is less common than it used to be, since YouTube auto-generates captions for most spoken-word content, but it still happens: music videos with no spoken dialogue, very short clips, or videos uploaded in a language YouTube's automatic captioning doesn't cover well.
This is generally a permanent state for a given video, though a brand-new upload can occasionally fail simply because YouTube hasn't finished generating automatic captions yet. If a video was uploaded minutes ago, waiting and retrying is worth it; if it's been up for weeks with no captions, it's not going to change on its own. Automatic captioning also covers some spoken languages far better than others, so a video in a less common language is more likely to have no usable caption track at all, even after plenty of time has passed.
Captions disabled
Captions can exist but be switched off by the uploader, which blocks access the same way as having none at all. There's no way to tell from the outside whether a video has captions turned off versus never having had any — both come back the same way: nothing to fetch.
Video unavailable
The video has been deleted, made private, or is restricted in a way that blocks access entirely. If a video was public when you first found the link but private or removed by the time you submit it, this is what you'll see. This is permanent unless the uploader changes the video's visibility back.
Members-only content
Some channels restrict videos to paying channel members. Scriptube can only process what's publicly accessible on YouTube — members-only and subscriber-only videos aren't reachable, the same way they aren't reachable to any visitor without a membership.
A note on video availability
"Unavailable" covers a few different states that all produce the same outcome from Scriptube's side: the video has been deleted, the uploader made it private, or access is otherwise blocked. Whatever the specific reason, if Scriptube can't reach the video publicly, there's nothing to process — the same as if you tried to open the link yourself and hit a dead end.
Checking before you submit
If you want to know what's available for a video before processing it, the languages endpoint lists every caption track YouTube actually offers:
curl https://scriptube.me/api/v1/videos/VIDEO_ID/languages \
-H "X-API-Key: YOUR_API_KEY"
An empty result means there's nothing to fetch for that video — no track exists in any language, regardless of which one you request.
What's coming, and what isn't yet
AI transcription for caption-less videos (via ElevenLabs) is coming soon but not available today — don't expect a "no captions" failure to resolve itself through that path yet. If you force it anyway, the API returns a 409 elevenlabs_disabled error rather than a transcript.
Permanent vs. worth retrying
| Reason | Usually permanent? |
|---|---|
| No captions (established video) | Yes |
| No captions (just uploaded) | Worth retrying after a delay |
| Captions disabled | Yes, unless the uploader re-enables them |
| Video unavailable (deleted/private) | Yes, unless visibility changes |
| Members-only content | Yes |
By default, Scriptube's retry endpoint skips items that failed for a permanent reason, since retrying won't change the outcome. You can force a retry anyway with include_permanent: true — useful if you suspect the situation changed, like a creator re-enabling captions. See retrying failed transcripts for the full options.
What this means for larger batches
In a batch of a handful of videos, one failure is easy to spot and investigate. In a 300-video channel batch, a few failures for these reasons are normal and not worth troubleshooting individually — check which ones are permanent versus temporary, retry what's worth retrying, and move on. See channel transcripts: limits and costs for handling failures at that scale.
Related reading
For what to do in the moment when a single video comes back empty, see YouTube transcript not available: here's what to do. To understand the difference between auto-generated and creator-uploaded caption tracks, which affects quality more than availability, see auto-generated vs. manual captions.
Error responses, if you're scripting against this
Errors Scriptube returns follow a consistent shape — {code, message, detail} — whether the problem is at the batch level or a specific item within it. If you're automating retries or alerts around failures, parse the detail field for the specifics rather than assuming every failure is the same kind of problem.
Check a video's available languages before you submit it with an API key from your dashboard, or browse the full reference in the API docs.