Errors

Error format

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

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

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

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. 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.
`invalid_query` / `invalid_max_results` / `invalid_country` / `invalid_include_stream_urls`	A TikTok LIVE search parameter is invalid. `invalid_country` lists the accepted codes.
`invalid_room_id` / `invalid_username` / `invalid_include_comments` / `invalid_comments_limit`	A TikTok LIVE room parameter 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_unavailable`	The video does not exist or cannot be accessed (private, removed, expired, …).
`video_not_yet_available`	The video is not published yet (e.g. a scheduled premiere).
`metadata_fetch_failed`	We could not reach the video to read its metadata, after our retries. This may be temporary.
`transcript_unavailable`	We could not retrieve a transcript, after our retries. This may be temporary; for speech-to-text, the async endpoints retry longer.
`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.
`live_not_found`	No such TikTok LIVE room: the room ID does not exist, or the account does not exist or has never gone LIVE. Not billed.

video_not_found is no longer returned: a video that does not exist is reported as video_unavailable, on every endpoint.

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.
`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, for a reason we did not recognise.
`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).
`502`	`live_room_unavailable`	TikTok did not serve the LIVE room. Retry in a moment. Not billed.
`503`	`system_overload`	The system is temporarily overloaded. Retry later.
`503`	`storage_not_configured`	File storage is not available.

API Documentation

Online media

Local Files

System

Error format

Error codes

400 — Bad request

401 — Unauthorized

402 — Payment required

403 — Forbidden

404 — Not found

413 — Payload too large

429 — Too many requests

451 — Unavailable for legal reasons

500 — Server error

502 / 503

​Error format

​Error codes

​400 — Bad request

​401 — Unauthorized

​402 — Payment required

​403 — Forbidden

​404 — Not found

​413 — Payload too large

​429 — Too many requests

​451 — Unavailable for legal reasons

​500 — Server error

​502 / 503

Error format

Error codes

400 — Bad request

401 — Unauthorized

402 — Payment required

403 — Forbidden

404 — Not found

413 — Payload too large

429 — Too many requests

451 — Unavailable for legal reasons

500 — Server error

502 / 503