Errors & Status Codes

Name: YouTubeTranscriptAPI
Price: 5 USD

Predictable shapes, sane retry semantics.

Error response shape

json

{
  "detail": "Human-readable error message",
  "code": "ERROR_CODE"
}

For payment-related errors (402) the detail field is an object with message, reason, action_label, and action_url fields so you can render an in-product upgrade prompt automatically.

json

{
  "detail": {
    "message": "You have an active plan, but you've run out of credits.",
    "reason": "insufficient_credits",
    "action_label": "Top up credits",
    "action_url": "https://YOUR_DOMAIN/top-up"
  }
}

Status code reference

Code	Meaning	Retry	Action
200	Success	—	Process the response.
400	Bad Request	❌	Check parameters.
401	Unauthorized	❌	Verify your API key.
402	Payment Required	❌	Top up credits or pick a plan.
404	Not Found	❌	Video / transcript unavailable.
408	Timeout	✅	Retry after 1–5s.
422	Validation Error	❌	Invalid URL / ID.
429	Rate Limited	✅	Respect Retry-After header.
500	Server Error	⚠️	Retry once, then contact support.
503	Unavailable	✅	Retry after 1–5s.

Charging rules

Successful (200) — 1 credit charged.
Cached HIT (200) — 1 credit charged. Speed is the benefit.
Free endpoints (200) — 0 credits, but require ≥1 active credit.
4xx and 5xx errors — never charged.
429 (rate limited) — never charged.