Advanced

Errors & rate limits

Every error uses one predictable envelope — a stable code, a human message, and whether retrying helps.

Error envelope

error response

{
  "error": {
    "code": "insufficient_credits",        // stable, machine-readable
    "message": "Not enough credits for this request. ...",
    "retryable": false,                     // whether retrying can help
    "request_id": "req_1f2e3d4c5b6a7988",  // quote this to support
    "details": { "required_credits": 18, "remaining_credits": 4 },
    "links": { "buy_credits": "https://app.vivideo.ai/subscription" }
  }
}

Codes

HTTP	Code	Cause & next step
400	`invalid_request · unknown_model`	Fix the request; details list what’s allowed and which model ids exist.
401	`missing_api_key · invalid_api_key · api_key_revoked`	Send a valid key.
402	`insufficient_credits`	Buy credits — see links.buy_credits.
403	`upgrade_required · free_limit_reached`	Upgrade the account — see links.upgrade.
404	`not_found`	No such resource for this account.
409	`duplicate_request · idempotency_in_flight`	Reuse the in-flight request or retry shortly.
413	`payload_too_large`	Keep JSON bodies under 256 KB.
429	`rate_limited`	Wait retry_after_seconds, then retry.
5xx	`upstream_error · internal_error`	Retryable — use exponential backoff.

✓

Branch on error.code, not the HTTP status or message text — codes are stable, messages may be reworded. Log request_id for every failure.

Rate limits

Scope	Limit
All requests, per key	120 / minute
All requests, per account (all keys)	240 / minute
Video creation (premium)	6 / min · 60 / hour · 200 / day
Video creation (free)	2 / min · 10 / day
Avatar create · brand-from-url · speech · uploads	5 / min · 100 / day
Webhook registration	10 / minute

Exceeding a limit returns 429 rate_limited with a Retry-After header and retry_after_seconds in the body. Limits are per account, so adding keys doesn't raise them. Status checks are cheap — poll at the suggested interval, not in a tight loop.

Idempotency

Send an Idempotency-Key header on POST /v1/videos so a network retry replays the original response instead of creating and charging a second video. Keys are scoped per account and remembered for 24 hours.

← Previous

Credits & billing

For AI agents

Machine-readable: interactive reference · openapi.yaml · llms-api.txt. Base URL https://api.vivideo.ai.