API Reference
Errors
RFC 7807 problem+json responses, every status code, and a clear retry policy.
Every error response is application/problem+json
(RFC 7807). Same shape across
every endpoint:
{
"type": "https://getyoutubetranscriber.com/api/errors/payment-required",
"title": "Payment Required",
"status": 402,
"detail": "You have no remaining credits.",
"code": "E_PAYMENT_REQUIRED",
"request_id": "req_01HX2…"
}You can include request_id to trace a single call end-to-end when
you file a support ticket.
Status code reference
| Status | Code | Retry? | What it means |
|---|---|---|---|
400 | E_BAD_REQUEST | No | Malformed JSON body or wrong content-type. |
400 | E_INVALID_CONTINUATION | No | Pagination cursor was tampered with or expired. |
401 | E_MISSING_API_KEY | No | No Authorization: Bearer <api_key> header. |
401 | E_INVALID_API_KEY | No | The API key isn't recognized. |
401 | E_INACTIVE_API_KEY | No | The API key was revoked or disabled. |
402 | E_FREE_GRANT_DEPLETED | No | Free 100-credit grant exhausted; subscribe. |
402 | E_SUBSCRIPTION_PAUSED | No | Subscription on hold or expired. Update payment in the dashboard. |
404 | E_NOT_FOUND | No | Video, channel, or playlist doesn't exist. |
404 | E_CAPTIONS_DISABLED | No | Video exists but the creator disabled captions. |
404 | E_VIDEO_UNAVAILABLE | No | Video is private, removed, or region-locked. |
404 | E_LANGUAGE_UNAVAILABLE | No | The requested lang isn't available for this video. |
408 | E_UPSTREAM_FAILURE | Yes | Upstream YouTube fetch timed out. Retry in 1–5s. |
422 | E_UNPROCESSABLE_ENTITY | No | Validation failed. See errors[] for field-level detail. |
422 | E_INVALID_VIDEO_URL | No | Couldn't extract a video id from the input. |
429 | E_RATE_LIMIT_EXCEEDED | Yes | You hit the per-minute ceiling. Honor Retry-After. |
500 | E_INTERNAL_SERVER_ERROR | Maybe | Our bug. Retry once; if it persists, contact support. |
502 | E_TRANSCRIPT_FETCH_FAILED | Yes | Upstream transcript provider unhealthy. Retry in 1–5s. |
Retry strategy
For retryable errors (408, 429, 502):
- If
Retry-Afteris present, wait at least that many seconds. - Otherwise back off exponentially: 1s, 2s, 4s, 8s.
- Give up after 3 attempts and log the
request_id.
For non-retryable errors, fix the request. Retrying won't help.
See Code examples for ready-made Python / Node helpers that implement this loop.