Errors

Public endpoints return business failures in a standard envelope:

{
  "error": {
    "code": "NO_TRANSCRIPT",
    "message": "Transcript not in your library. Use POST /v1/transcript to extract or save it."
  }
}

Plan-gated 402 responses may also include actionLabel, actionUrl, and the backwards-compatible upgrade_url alias. A language miss that cannot fall back to speech recognition returns 404 with availableLanguages.

Some framework-level failures are still returned as a flat string body — for example { "error": "unauthorized" }, { "error": "rate_limited" }, or { "error": "invalid_credential" }. A robust client reads error as either an object or a string and only inspects error.code when it is present.

HTTP statuses

Status	Meaning	Client action
`400`	Malformed input	Fix the request before retrying.
`401`	Missing or invalid credential	Supply or rotate the API key.
`402`	Plan or entitlement gate	Surface the returned action URL.
`403`	Valid key with insufficient scope	Use a key with the required scope.
`404`	Resource or requested language not found	Inspect the response details and available languages.
`409`	Resource state conflict	Wait for the required state, then retry.
`422`	Valid JSON with unsupported values or source	Correct the semantic input.
`429`	Rate limit exceeded	Respect `Retry-After` and back off.
`502`	A dependent capability or upstream discovery call failed	Retry with bounded exponential backoff; do not treat it as "no transcript".
`503`	A required capability is unavailable or unconfigured	Do not treat it as "no transcript"; surface the error.

POST /v1/transcript also uses 202 for accepted asynchronous speech recognition. It is a successful handoff, not an error.

Common error codes

Code	Meaning
`INVALID_VIDEO`	The supplied URL or platform id is invalid.
`NO_TRANSCRIPT`	A usable transcript is not available for the request.
`LANGUAGE_NOT_AVAILABLE`	Captions exist in other languages but none matched the request, and speech recognition was not allowed.
`NO_VIDEO`	The post is reachable but has no video to transcribe: a photo or text post, or a link card to a video on another site. Do not retry.
`NO_SPEECH`	The media was transcribed and no speech was detected (silence, music only, or a muted source). Nothing is charged to the ASR allowance. Do not retry.
`X_BROADCAST_UNSUPPORTED`	The X post is a live broadcast or a replay of one, which is not supported. Decided from the post lookup, so nothing is downloaded, transcribed, or charged. Do not retry.
`LOGIN_REQUIRED`	YouTube says the video is private or requires signing in. Only returned when the platform states it; a bot check on one of our egress routes is retried elsewhere and never reported as private. Do not retry.
`AGE_RESTRICTED`	The YouTube video is age-restricted and requires signing in. Decided within seconds; nothing is downloaded, transcribed, or charged. Do not retry.
`MEMBERS_ONLY`	The YouTube video is only available to the channel's members. Decided within seconds; nothing is downloaded, transcribed, or charged. Do not retry.
`REGION_BLOCKED`	YouTube does not offer the video in the region our servers are in. Decided within seconds; retrying does not change it.
`UNAVAILABLE`	The source is removed or inaccessible.
`UPLOAD_INVALID`	A multipart upload failed declaration, media-type, or integrity validation.
`IDEMPOTENCY_CONFLICT`	The same `Idempotency-Key` was reused with a different request.
`IP_BLOCKED`	The source platform temporarily blocked extraction infrastructure.
`PO_TOKEN_REQUIRED`	The source platform requires additional login state.
`VIDEO_TOO_LONG`	The media exceeds the current plan's duration limit.
`RATE_LIMITED`	The caller exceeded its current request window.
`UPGRADE_REQUIRED`	The account is not eligible to use the requested API capability.
`INSUFFICIENT_CREDITS`	The account cannot start the gated operation.
`TRANSCRIPT_QUOTA_EXCEEDED`	The transcript allowance for the current period is exhausted.
`ASR_QUOTA_EXCEEDED`	The ASR minute allowance for the current period is exhausted.
`ASR_CONCURRENCY_LIMIT`	The plan's concurrency limit is fully in use; ASR minutes are not exhausted. Retry once an in-flight task finishes.
`BATCH_LIMIT_EXCEEDED`	The batch exceeds the plan's per-job item limit.

Retry guidance

Retry 429 and transient 503 responses only. Honor Retry-After when supplied, add jitter, cap the delay, and set a maximum attempt count. Do not automatically retry authentication, scope, validation, or plan failures without changing the request or credential.

HTTP statuses

Common error codes

Retry guidance

On this page