ReferenceMarkdown

Errors

A request error is an HTTP status of 400 or above: nothing was started and nothing is held. A generation that is accepted and then stops is not a request error: it ends failed, free, see Why a generation failed.

Every request error has the same shape. Every answer carries an X-Request-Id header: quote it to support.

json

{
  "error": {
    "message": "`resolution` must be one of: 480p, 720p, 1080p.",
    "type": "invalid_request_error",
    "code": "invalid_input"
  }
}

code is stable: branch on it. message is written for people and can change.
type groups codes: invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error, service_unavailable_error.
Some errors add fields beside error (price_usd, wallet, limits, observed, plan, reset_at, request_id).
429 and 503 answers carry a Retry-After header in seconds when there is a known wait.

Status	Code	When	Fix
400	`invalid_json`	The body is not a JSON object.	Send a JSON object with `Content-Type: application/json`.
400	`invalid_request`	A field has the wrong type, is too long, or is not an input field at all. The message names the field.	Fix or remove that field.
400	`invalid_input`	The model does not take this input: a field it does not list, a value not in `values`, out of range, too many images, a missing required field. The message names the field and the allowed values.	Read `GET /v1/models/{id}` and send only its `params`.
400	`variant_unavailable`	This model is not offered with these options right now. The message lists the priced options.	Pick one of the listed options.
400	`invalid_limit`, `invalid_status`, `invalid_model`, `invalid_starting_after`	A query value of `GET /v1/generations` is not valid.	See List generations.
400	`max_price_exceeded`	The price is over `max_price_usd`, the older name of the cap. `price_usd` has the price.	Use `max_cost_usd`.
400	`invalid_idempotency_key`	The `Idempotency-Key` is not 8 to 100 of `A-Z a-z 0-9 _ : . -`.	Send a valid key, such as a UUID.
400	`empty_file`, `upload_interrupted`	An upload has no bytes, or the connection ended before the whole file arrived.	Send the whole file as the request body.
401	`unauthorized`	The key is missing, unknown or revoked.	Send `Authorization: Bearer vidlab_sk_...` with a live key.
401	`key_expired`	The key's expiry date has passed.	Create a new key under API keys.
402	`key_quota_exceeded`	The key reached its own spend quota.	Raise the key's quota, or use another key.
403	`ip_not_allowed`	The key has an address list and this address is not on it.	Add the address to the key's list, or use another key.
403	`model_not_allowed`	The key has a model list and this model is not on it.	Allow the model on the key, or use another key.
403	`api_key_required`	Generations need a `vidlab_sk_` key; another kind of token was sent.	Use an API key from the dashboard.
403	`api_key_scope_forbidden`	The key is scoped and this call needs another scope.	Use a full-access key.
403	`developer_access_forbidden`	This account does not have API access yet.	Contact support@vidlab.ai.
404	`model_not_found`	No listed model has that id.	List ids with `GET /v1/models`.
404	`generation_not_found`	This account has no generation with that id.	Use a key of the account that started it.
404	`output_not_found`	`/content/{n}` is past the files the generation made.	Use a smaller number.
404	`not_found`	No such endpoint.	Check the method and path.
405	`method_not_allowed`	Wrong method for this path.	Use the method in the Quickstart.
409	`not_ready`	`/content` was asked for before the generation succeeded.	Poll until `succeeded`, then retry after `Retry-After`.
409	`generation_failed`	`/content` was asked for a failed generation.	Read its `error`.
413	`request_too_large`	The JSON body is over 2 MB.	Send files as links or uploads, not inline.
413	`file_too_large`	An upload is over the limit for its kind.	Send a smaller file.
415	`unsupported_media_type`	An upload is not a picture, video or sound we take, or is not what its `Content-Type` says.	Send a supported type.
422	`max_cost_exceeded`	No route can run the call for `max_cost_usd` or less. `price_usd` has the price.	Raise `max_cost_usd`, or lower the resolution or duration.
422	`max_wait_exceeded`	No route is expected to finish within `max_wait_s`. `estimated_seconds` has the usual time.	Raise `max_wait_s`.
429	`rate_limited`	Too many catalogue, quote or upload calls from your address or account.	Wait for `Retry-After`.
429	`read_rate_limited`	This key read (polled, listed, fetched files) over 1,200 times this minute.	Wait for `Retry-After`; poll every few seconds, or read many at once with `GET /v1/generations`.
429	`request_per_minute`	This key started too many generations this minute.	Wait for `Retry-After`, or spread calls out.
429	`request_per_minute_user`	Your account started too many generations this minute, across keys.	Wait for `Retry-After`.
429	`request_per_day`	Your account reached its daily request limit.	Wait for `reset_at` (midnight UTC).
429	`api_wallet_exhausted`	The balance does not have room to reserve this price. `wallet` has the balance.	Add credit, or wait for running generations to finish.
429	`api_key_budget_exhausted`	This key reached its monthly budget.	Use another key, or wait for the next cycle.
429	`too_many_uploads`	Too many uploads are running at once.	Wait for one to finish, then try again.
429	`daily_upload_limit`	The account has uploaded its daily share.	Wait until tomorrow, or send links.
503	`api_wallet_reconciliation_required`	The balance is held for a billing review.	Contact support. Do not retry until it is cleared.
503	`model_unavailable`	The model is busy right now.	Retry after `Retry-After`.
500, 502	`api_error`, `internal_error`, `unavailable`	Something went wrong on our side.	Retry with the same `Idempotency-Key` after a short wait.

Retrying safely

Retry 5xx, 429 and model_unavailable after the Retry-After wait (or a short backoff). Retry other 4xx errors only after you change the request.
Always send an Idempotency-Key on POST /v1/generations. A retry with the same key returns the generation the first call made, so a lost answer never starts a second, paid one.
A failed generation is final. To try again, submit a new one with a new Idempotency-Key.