DocsVidNext API

Errors

The error format and every error code — what it means and what to do.

Every error has the same shape:

{ "error": { "type": "invalid_request_error", "code": "unknown_theme_mode", "message": "…", "param": "theme.mode", "request_id": "req_…" } }

Branch on code — it's stable. message is for people and may change; param names the field at fault. Every response carries a Request-Id header: include it when you write to support. New codes may be added.

Requests

HTTP	`code`	What to do
400	`invalid_request`, `invalid_json`	Fix the field named in `param`.
400	`unsupported_language`, `duration_out_of_range`, `theme_format`, `unknown_theme`, `unknown_theme_mode`, `level_not_supported`, `caption_style_not_allowed`, `thumbnail_style_not_usable`, `music_not_found`, `channel_not_usable`, `tts_language_unsupported`, `voice_language_mismatch`	Pick a value from your lists — see Choose settings.
400	`member_pays_own_credits`	That member pays with their own credits; a team key can't make videos for them.
404	`preset_not_found`, `member_not_found`, `video_not_found`, `video_deleted`	Check the ID, name or email.
409	`preset_ambiguous`	Two presets share the name — send the ID (the matching IDs are in `details`).
409	`idempotency_key_reused`	The same `Idempotency-Key` with a different body — use a new key.
409	`video_not_cancelable`, `video_not_finished`, `video_not_ready`	The video isn't in the right state yet.
422	`script_not_narration`	Your script reads like instructions — move them to `prompt`, or send `"script_check": "off"`.
422	`prompt_blocked`, `script_too_long`	Change the prompt, or shorten the script.

Access and account

HTTP	`code`	What to do
401	`missing_api_key`, `invalid_api_key`	Send a valid key in `Authorization: Bearer`.
402	`insufficient_credits`	Top up — `details` has `needed` and `have`.
402	`plan_required`, `team_limit_reached`	A plan is needed, or the team member's monthly limit is reached.
403	`insufficient_scope`	The key lacks the permission — edit it in Settings → VidNext API.
403	`api_access_disabled`, `account_suspended`, `account_limited`	The API isn't on for this account (it comes with the Studio and Enterprise plans), or the account is limited — write to support.
403	`theme_not_available`, `voice_not_usable`, `preset_not_usable`, `feature_not_available`	Not available to this account (or not shared with this member).
403	`storage_full`	Delete finished videos, or turn on auto-delete for the key.

Limits and outages

HTTP	`code`	What to do
429	`rate_limited`	Wait for the `Retry-After` header's seconds.
429	`daily_limit_reached`, `key_daily_limit_reached`	The day's API videos are used up; the count resets at 00:00 UTC (`Retry-After`).
503	`try_again`	A check couldn't run just now — retry with the same `Idempotency-Key`.
503	`secrets_not_configured`	Webhooks and `callback_url` can't be signed just now — try again later, or check the video's status instead.
500	`internal_error`	Retry with the same `Idempotency-Key`; if it repeats, write to support with the `Request-Id`.

A video that fails after it started reports its reason in the video's error (and in video.failed), not as an HTTP error.