Errors | CheapVids API documentation

Error format

Every error uses the same JSON envelope:

{
  "error": {
    "code": "plan_quota_exhausted",
    "message": "Studio daily quota used up",
    "plan": "studio",
    "details": { "kind": "image", "limit": 45, "used": 45, "resets_at": "2026-10-04T00:00:00Z" }
  }
}

code is stable and meant for your code. message is for people and may change.
plan is "studio", "credits" or null. Every error about a plan group names the group.
details depends on the code; it is always an object.

Error codes

HTTP	Code	Meaning	Details
400	`plan_required`	`plan` is missing
401	`unauthorized`	Missing, malformed or revoked API key
402	`no_active_plan`	No active Studio plan (`plan: "studio"` only)
402	`plan_quota_exhausted`	The Studio daily quota for this kind is used up	`kind`, `limit`, `used`, `resets_at`
402	`insufficient_credits`	Not enough credits (`plan: "credits"`)	`required`, `available`
403	`banned`	The account is suspended
403	`first_payment_required`	API keys and webhooks unlock after the first USDT payment
403	`terms_not_accepted`	You must accept the current terms in the web app	`current_version`
404	`not_found`	The job does not exist, is not yours, or the content URL is not valid
409	`idempotency_conflict`	The `Idempotency-Key` was used with a different body, or a duplicate request is still running
409	`not_cancellable`	The job already runs and cannot be cancelled
410	`result_expired`	The download window of the result has ended	`expired_at`
413	`invalid_parameters`	The request body is too large	`max_bytes`
422	`invalid_parameters`	A parameter is wrong	`field`, `reason`
422	`model_not_in_plan`	The model is not included in Studio
422	`content_policy_violation`	The prompt was blocked by the content policy; nothing is charged
429	`rate_limited`	Too many requests or downloads	`scope`: `key`, `plan`, `auth`, `ip`, `bandwidth`, `job`; for the last two `limit_bytes`
429	`queue_full`	You have 20 jobs waiting	`max_pending`
502	`result_unavailable`	The result cannot be retrieved right now	`generation_id`
503	`model_unavailable`	The model is under maintenance or paused
504	`generation_pending`	The OpenAI compatible endpoint timed out waiting for the image	`generation_id`
500	`internal`	Something went wrong on our side

details.reason of invalid_parameters can be required, too_long, unsupported, not_allowed, too_few, too_many, max_keys, max_endpoints, invalid_range, multi_range_not_supported, among others.

A job that starts and then fails is reported on the job itself: status: "failed", error_code and error (with a safe reason such as timeout or source_failed). Failed jobs are refunded to the group that was charged.

Retries

429 and 5xx are safe to retry with the same Idempotency-Key; wait for Retry-After seconds when the header is present.
4xx other than 429 will not succeed on a retry without a change on your side.