Errors

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 aitijya@bestvideotranscriptapi.com.

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".

Get started

Concepts

Agents

Reference

Codes

When to retry

​Codes

​When to retry

Codes

When to retry