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

# Errors

> Error format and the error codes returned by the VidNavigator API

## Error format

The API uses standard HTTP status codes and returns errors as JSON:

```json theme={null}
{
  "status": "error",
  "error": "video_too_long",
  "message": "This video is longer than 10 minutes. Use POST /v1/transcribe/async instead.",
  "docs_url": "https://docs.vidnavigator.com/guides/async-jobs"
}
```

| Field      | Description                                                                   |
| ---------- | ----------------------------------------------------------------------------- |
| `status`   | Always `error`.                                                               |
| `error`    | Machine-readable code. Branch on this, not on `message`.                      |
| `message`  | Human-readable explanation.                                                   |
| `docs_url` | Present on actionable errors: a link to the page that explains how to fix it. |

<Note>
  For [async jobs](/guides/async-jobs), a job that fails in the background is reported by the poll endpoint (`200`, `task_status: "failed"`) with a `data.error` object carrying the same `error` code plus the `http_status` the synchronous endpoint would have returned.
</Note>

## Error codes

### 400 — Bad request

| `error`                                    | Meaning                                                                                                                                                                                                                               |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request_body_required`                    | The request body is missing.                                                                                                                                                                                                          |
| `missing_parameter`                        | A required parameter is missing.                                                                                                                                                                                                      |
| `invalid_parameter`                        | A parameter has an invalid value.                                                                                                                                                                                                     |
| `invalid_url`                              | The URL is malformed.                                                                                                                                                                                                                 |
| `unsupported_url` / `unsupported_platform` | The URL or platform is not supported by this endpoint.                                                                                                                                                                                |
| `no_videos_found`                          | The post carries no video (e.g. an image-only Instagram carousel).                                                                                                                                                                    |
| `video_too_long`                           | The media is longer than **10 minutes**, the limit for synchronous endpoints. Use the [async endpoint](/guides/async-jobs). The metadata fetch that read the duration is billed and not refunded; no `transcription_hour` is charged. |
| `invalid_schema`                           | The extraction schema is invalid.                                                                                                                                                                                                     |
| `input_too_large`                          | The input exceeds the size the endpoint accepts.                                                                                                                                                                                      |
| `invalid_cursor`                           | The pagination cursor is invalid.                                                                                                                                                                                                     |

### 401 — Unauthorized

Missing, invalid or deactivated API key.

### 402 — Payment required

| `error`          | Meaning                                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `limit_exceeded` | Not enough credits, or no active subscription. Async submit endpoints return it when less than 60 seconds of transcription credit is left. |

### 403 — Forbidden

| `error`              | Meaning                                                     |
| -------------------- | ----------------------------------------------------------- |
| `access_denied`      | The API key lacks permission for this resource or endpoint. |
| `content_restricted` | The content requires login or age verification.             |

### 404 — Not found

| `error`                    | Meaning                                                                                                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `video_not_found`          | The video does not exist.                                                                                                   |
| `video_unavailable`        | The video exists but cannot be accessed (private, removed, …).                                                              |
| `transcript_not_available` | No transcript could be retrieved or generated.                                                                              |
| `file_not_found`           | The uploaded file does not exist.                                                                                           |
| `task_not_found`           | The async task does not exist, has expired (results are kept 1 hour after the job finishes), or belongs to another account. |

### 413 — Payload too large

| `error`                  | Meaning                     |
| ------------------------ | --------------------------- |
| `storage_quota_exceeded` | Your storage quota is full. |

### 429 — Too many requests

| `error`                | Meaning                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `rate_limit_exceeded`  | Per-endpoint rate limit exceeded. See [Rate Limiting](/api-reference/rate-limiting).       |
| `too_many_active_jobs` | Too many async jobs already running for this account. Wait for some to finish, then retry. |

### 451 — Unavailable for legal reasons

| `error`          | Meaning                                                        |
| ---------------- | -------------------------------------------------------------- |
| `geo_restricted` | The content is not available in the region it is fetched from. |

### 500 — Server error

| `error`                   | Meaning                                                      |
| ------------------------- | ------------------------------------------------------------ |
| `metadata_fetch_failed`   | The video's metadata could not be fetched from the platform. |
| `audio_extraction_failed` | The audio could not be extracted from the video.             |
| `transcription_failed`    | Speech-to-text failed.                                       |
| `extraction_failed`       | Structured data extraction failed.                           |
| `internal_server_error`   | Unexpected server error.                                     |

Charges are reverted when a request fails with a server error.

### 502 / 503

| Status | `error`                  | Meaning                                                               |
| ------ | ------------------------ | --------------------------------------------------------------------- |
| `502`  | —                        | Upstream fetch failed (e.g. the tweet could not be retrieved from X). |
| `503`  | `system_overload`        | The system is temporarily overloaded. Retry later.                    |
| `503`  | `storage_not_configured` | File storage is not available.                                        |