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=dQw4w9WgXcQ
  • https://youtu.be/dQw4w9WgXcQ
  • https://www.youtube.com/embed/dQw4w9WgXcQ
  • https://www.youtube.com/shorts/dQw4w9WgXcQ
  • https://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 404 is 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_code was not invalid-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.