> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bestvideotranscriptapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

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

Every error has the same shape:

```json theme={null}
{
   "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](mailto:aitijya@bestvideotranscriptapi.com).

## Codes

| Code | Status | Meaning and fix |
| - | - | - |
| `UNAUTHENTICATED` | 401 | The API key is missing, wrong or expired. See [Authentication](https://docs.bestvideotranscriptapi.com/authentication.md). |
| `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](https://docs.bestvideotranscriptapi.com/concepts/uploads.md). |
| `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](https://docs.bestvideotranscriptapi.com/concepts/jobs.md) returns the same `error` object inside a `200` poll response with `"status": "failed"`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.