Errors

Every error code, its HTTP status and what to do about it.

Every error has the same shape:

{
   "error": {
      "code": "CAPTIONS_UNAVAILABLE",
      "message": "No captions found. Use mode=auto or mode=generate to transcribe the audio instead.",
      "requestId": "bom1::iad1::abc12-1730000000000-0123456789ab"
   }
}

• Branch on code. It won’t change.
• message is written for people. It’s safe to show your users.
• Every response, success or error, has an x-request-id header. Include it when you email [e-mail].

Codes

Code	Status	Meaning and fix
UNAUTHENTICATED	401	The API key is missing, wrong or expired. See Authentication.
INVALID_REQUEST	400	A bad parameter: url isn’t a usable link, or mode, lang or text has a bad value. The message says which.
UNSUPPORTED_PLATFORM	400	A video site we don’t support yet, like Vimeo or TikTok.
NOT_A_VIDEO	422	No video at the link: a story, photo, carousel, text post, X Space or LinkedIn article. For an X post, the /video/<n> number may be too high.
VIDEO_UNAVAILABLE	404	The video is private, removed, age-restricted or region-locked.
MEDIA_NOT_FOUND	422	No audio or video at the link. Link straight to the file, not a web page, or upload it.
CAPTIONS_UNAVAILABLE	404	mode=native and the video has no captions. Use auto or generate.
LANGUAGE_NOT_AVAILABLE	404	No captions in the requested lang. availableLangs lists the ones that exist.
NO_SPEECH_FOUND	422	The media has no audio track, or no speech.
FILE_TOO_LARGE	422	Over 2 GB. Send just the audio track. Includes sizeBytes and maxSizeBytes.
VIDEO_TOO_LONG	422	Over 2 hours, too long for AI transcription. YouTube videos with captions work at any length with mode=native. Includes durationSeconds and maxDurationSeconds.
LIVE_STREAM	422	A live stream or upcoming premiere. Try again after it ends.
AI_HOURS_EXHAUSTED	402	Not enough AI time left for this video. Includes aiMinutesNeeded, aiMinutesRemaining, refillsAt and billingUrl.
CAPTIONS_LIMIT_REACHED	402	This month’s caption transcripts are used up. Includes refillsAt and billingUrl.
RATE_LIMITED	429	Over your plan’s requests per second. Wait Retry-After seconds. Includes billingUrl.
JOB_NOT_FOUND	404	No job with that ID on your account.
UPSTREAM_FAILURE	502	Something broke on our side. Retry after Retry-After seconds (60).

When to retry

Retry	Codes
After Retry-After	RATE_LIMITED, UPSTREAM_FAILURE
Later	LIVE_STREAM once the stream ends. AI_HOURS_EXHAUSTED and CAPTIONS_LIMIT_REACHED after refillsAt or an upgrade.
Never	Everything else. The same request fails the same way.

A failed job returns the same error object inside a 200 poll response with "status": "failed".