Transcript Errors & Retries¶
Everything that can go wrong on GET /v1/youtube/transcript and the batch endpoints, what the response body looks like, and what a sensible retry policy is.
| Method | Endpoint | Failure mode |
|---|---|---|
GET |
/v1/youtube/transcript |
Synchronous — error returned in the same request |
POST |
/v1/youtube/transcript/batch |
Async — per-item failures reported in the job results |
GET |
/v1/youtube/transcript/batch/{job_id} |
404 when the job expired or never existed |
Base URL¶
https://media.toolkitapi.io
Requires an X-API-Key header.
Error body shape¶
Errors are Supadata-compatible, so a client written against Supadata's shapes works unchanged:
{
"detail": {
"error": "transcript-not-found",
"message": "No transcript available for this video",
"details": null,
"documentationUrl": "https://supadata.ai/docs/errors"
}
}
| Field | Description |
|---|---|
detail.error |
Machine-readable code — branch on this, not on the message |
detail.message |
Human-readable reason; wording can change |
detail.details |
Extra context or null |
detail.documentationUrl |
Pointer to the upstream error catalogue |
Note
FastAPI wraps the payload in detail, unlike Supadata's flat body. If you share a client with Supadata, read err.detail ?? err once at the edge rather than everywhere.
Single-video errors¶
| Status | detail.error |
Cause | Retry? |
|---|---|---|---|
400 |
invalid-request |
url did not contain a parseable video ID |
No — fix the input |
404 |
transcript-not-found |
Video has no captions in the requested (or any fallback) language, or the video is unavailable/private | Usually no |
401 |
Invalid or missing API key (plain string detail) |
Missing or invalid X-API-Key |
No |
429 |
— | Rate limit exceeded | Yes, with backoff |
Auth failures bypass the Supadata-compatible envelope — 401 returns {"detail": "Invalid or missing API key"} as a plain string, so don't assume detail is always an object.
Accepted url forms¶
The video ID is extracted from the URL before anything else happens, so these all work:
https://www.youtube.com/watch?v=dQw4w9WgXcQhttps://youtu.be/dQw4w9WgXcQhttps://www.youtube.com/embed/dQw4w9WgXcQhttps://www.youtube.com/shorts/dQw4w9WgXcQhttps://www.youtube.com/live/dQw4w9WgXcQ- the bare 11-character ID
dQw4w9WgXcQ
Anything else — a channel URL, a playlist URL without v=, a shortened link with extra path segments — comes back as invalid-request. Resolve shorteners client-side before calling.
Batch jobs never fail on a single video¶
A batch job reports completed even when every item inside it failed. Failures live in results[]:
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"results": [
{"id": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "status": "succeeded", "lang": "en", "content": []},
{"id": "not-a-video", "url": "not-a-video", "status": "failed", "error_code": "invalid-request", "error": "Could not parse video ID from: not-a-video"}
],
"stats": {"total": 2, "succeeded": 1, "failed": 1},
"completedAt": "2026-10-24T05:12:09.331Z"
}
error_code |
Meaning | Retry? |
|---|---|---|
invalid-request |
URL or ID could not be parsed | No |
transcript-not-found |
No captions available for that video | No |
Check stats.failed — a completed job with stats.failed > 0 still needs attention.
Job lifecycle and expiry¶
| Status | Meaning |
|---|---|
queued |
Accepted, background task not started |
active |
Processing URLs; results is still [] |
completed |
All items processed (successes and failures) |
failed |
The job itself failed — status is currently only set by internal errors |
Jobs live in memory with a 1-hour TTL from creation. After that, polling returns:
{"detail": {"error": "not-found", "message": "Job <id> not found or expired", "details": null, "documentationUrl": "https://supadata.ai/docs/errors"}}
Consequences worth designing around:
- Persist results immediately. Once a job is fetched as
completed, write the results somewhere durable — you cannot re-read them an hour later. - Don't queue a job and walk away for longer than the TTL; you will lose the results, not just the handle.
- A
404is indistinguishable from "wrong ID" and "expired" — treat both as "resubmit if you still need it".
Retry policy¶
import random
import time
import httpx
TRANSIENT = {429, 500, 502, 503, 504}
def get_transcript(url: str, lang: str = "en", attempts: int = 3) -> dict | None:
"""Fetch one transcript with bounded retries. Returns None when it is a hard no."""
for attempt in range(attempts):
resp = httpx.get(
"https://media.toolkitapi.io/v1/youtube/transcript",
headers={"X-API-Key": MEDIA_API_KEY},
params={"url": url, "lang": lang},
timeout=60,
)
if resp.status_code == 200:
return resp.json()
if resp.status_code in TRANSIENT:
time.sleep(min(2 ** attempt + random.random(), 30))
continue
if resp.status_code in (400, 404):
return None # unparseable or no captions — retrying won't help
resp.raise_for_status()
return None # gave up after transient errors
const TRANSIENT = new Set([429, 500, 502, 503, 504]);
async function getTranscript(url, lang = "en", attempts = 3) {
for (let attempt = 0; attempt < attempts; attempt++) {
const q = new URLSearchParams({ url, lang });
const res = await fetch(
`https://media.toolkitapi.io/v1/youtube/transcript?${q}`,
{ headers: { "X-API-Key": process.env.MEDIA_API_KEY } }
);
if (res.ok) return res.json();
if (res.status === 400 || res.status === 404) return null; // hard no
if (!TRANSIENT.has(res.status)) throw new Error(`${res.status} ${await res.text()}`);
const wait = Math.min(2 ** attempt * 1000 + Math.random() * 500, 30_000);
await new Promise((r) => setTimeout(r, wait));
}
return null;
}
Rules of thumb:
- Retry:
429,5xx, network errors. Exponential backoff with jitter, max 3 attempts. - Don't retry:
400 invalid-request,404 transcript-not-found. The answer will not change. - Resubmitting batch items: run a second batch containing only the failed URLs whose
error_codewas notinvalid-request, and only if you suspect a transient upstream hiccup. There is no retry inside a batch. - Rate: poll batch jobs at 2s or slower — jobs finish in seconds for short videos.
Language fallback¶
lang is a preference, not a contract. When the requested track is missing, the service returns whatever track the video has and reports the actual language:
{
"id": "dQw4w9WgXcQ",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"lang": "de",
"availableLangs": ["de", "en"],
"content": [{"text": "Wir kennen uns nicht", "offset": 0.0, "duration": 3.4, "lang": "de"}]
}
Always check lang against what you asked for, and use availableLangs to decide whether to request an exact track instead of guessing again.
Related¶
- Batch Transcripts — submit/poll flow for up to 20 videos
- Media Conversion — transcode the video after fetching metadata
- Conversion Errors & Troubleshooting — FFmpeg-side failures