Guides / Errors

Errors

A refused request answers with an HTTP status and an error body. A task that fails after it was accepted reports error.code on the task and in its webhook.

Markdown fileTry in PlaygroundDocs version r8

Error body

Every error response has the same shape. Branch on error.code, not on the message, which may change.

422 invalid_input

{
  "error": {
    "code": "invalid_input",
    "message": "input does not match the model's schema",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8a1d40be7c26f5e13",
    "errors": [
      { "path": "/settings/duration", "rule": "required" },
      { "path": "/settings/aspect_ratio", "rule": "value_not_allowed" }
    ]
  }
}

Field	Meaning
`code`	Stable machine-readable reason.
`message`	A short description for logs. It never contains your input.
`retryable`	`true` only for 429 and 503: the same request may succeed later.
`request_id`	Include it when you contact support.
`errors`	On 422 input errors only: each failed field, as a JSON pointer into `input` (`path`) and a rule name (`rule`).

Request errors

These are the values of error.code on a refused request. The request created nothing and held no Credits.

HTTP	`error.code`	Meaning	What to do
400	`invalid_input`	The request body is not valid JSON or does not have the request shape.	Fix the body. Do not retry unchanged.
401	`invalid_credentials`	The API key is missing, malformed, expired or revoked.	See Authentication.
402	`insufficient_balance`	Available Credits cannot cover the hold.	Top up, then submit again.
402	`balance_negative`	The balance is below zero: a task's actual usage went past its hold and your balance, and Credits are owed.	Top up to bring the balance back to zero or above, then submit again.
403	`scope_denied`	The key lacks the scope for this operation or project.	Use a key with the scope.
403	`ip_not_allowed`	The request came from outside the key's IP allowlist.	Call from an allowed address.
403	`model_not_allowed`	The key's model allowlist excludes this model.	Allow the model on the key.
403	`budget_exceeded`	The key's daily or monthly spend limit would be exceeded.	Raise the limit or wait for the next UTC day or month.
403	`spending_blocked`	Spending is paused on the organization.	Contact support.
404	`resource_not_found`	The model, task or asset does not exist in this project.	Check the ID and the key's project.
404	`draft_not_found`	The `draft_task` names no succeeded draft of this project.	Use the ID of your own succeeded draft.
409	`conflict`	The request conflicts with the resource's state.	Read the resource, then decide.
409	`storage_quota_exceeded`	The organization's upload storage is full.	Delete assets you no longer need.
422	`invalid_input`	`input` does not match the model's schema, for example a media URL that is not `https`. `errors` lists each field.	Fix the fields named in `errors`.
422	`tier_not_sold`	The input is valid but selects a price tier your project cannot buy.	Change the resolution, the media or the length.
422	`input_media_invalid`	A media link's file has a format the model does not take in that field.	Send a supported format. See Model inputs and media.
422	`input_media_too_large`	A media link's file is larger than the model allows for its kind.	Send a smaller file. See Model inputs and media.
422	`input_duration_out_of_range`	A measured input video or audio is shorter or longer than the model or tier accepts, alone or in total. `errors` names each file or total with its rule (see below). A length the model's rules accept but the selected tier cannot price comes without `errors`; its message names the range the tier accepts.	Trim the media or pick another tier.
422	`draft_expired`	The draft is older than 7 days.	Generate a new draft.
429	`rate_limited`	A request rate or the open-task backlog is used up.	Wait `Retry-After` seconds. See Rate limits.
429	`concurrency_limited`	As many tasks of this media type are running as your limit allows: by default 3 video tasks at once per organization (10 image, 10 audio). See Rate limits.	Wait `Retry-After` seconds, or queue on your side.
500	`request_failed`	The request failed on our side.	For a create, check recent tasks before submitting again.
503	`temporarily_unavailable`	The service is briefly unavailable.	Retry later with backoff.

Most creates are funded just after they are accepted. Then a balance, budget or spending refusal does not answer the request: the task is accepted with HTTP 202 and fails with the same code. See [Task errors](#task-errors).

The media checks read only the start of each linked file. When a check cannot read a file's format, size or duration, the request is still accepted and the model checks the file when it fetches it.

Estimate a price refuses the same input and media as a create, with the same errors. A create can still fail where an estimate succeeded: on balance or budget, on the rate and concurrency limits, or when a price changes in between.

Important

A timeout or a dropped connection on a create is not an error body: the task may exist. Do not resend the create. Follow Interrupted submissions.

Input field rules

A 422 lists one entry per failed field. Common rule values:

`rule`	Meaning
`required`	A required field is missing.
`field_not_allowed`	The model's schema does not list this field.
`wrong_type`	The value has the wrong JSON type.
`value_not_allowed`	The value is not one of the allowed values here.
`out_of_range`	A number or length is outside its limits.
`bad_format`	A string does not have the required format, for example a media URL.
`too_many_items`, `too_few_items`	A list has too many or too few entries.
`prompt_or_contents`	Send exactly one of `prompt` and `contents` (Kling 4.0).
`frames_with_references`	Image frames cannot be combined with reference media.
`ratio_must_be_adaptive`	This kind of input only accepts `adaptive`.
`draft_not_upgradable`	Only a 480p draft can be turned into a final video.
`media_format`, `media_size`	With `input_media_invalid` or `input_media_too_large`: the linked file's format or size.
`video_length`, `media_length`, `video_total_too_long`, `audio_total_too_long`, `input_plus_output_too_long`	With `input_duration_out_of_range`: one file, or the files together, have a length the model does not accept.

Each model has a reference page under Models in the docs navigation, with its fields, allowed values and rules.

Task errors

A task accepted with HTTP 202 can still close without a result. Its status is failed or canceled and error.code names the reason. The webhook carries the same code as error_code, except delivery_failed and generation_failed, for which it may omit error_code. A task that closes without a result is not charged; its hold is released.

`error.code`	Meaning	What to do
`insufficient_balance`	Funding was refused: the balance could not cover the hold.	Top up, then submit a new task.
`balance_negative`	Credits were owed when the task came to be funded.	Top up to bring the balance back to zero or above, then submit a new task.
`budget_exceeded`	The key's daily or monthly spend limit would be exceeded.	Raise the limit or wait for the next UTC day or month.
`spending_blocked`	Spending is paused on the organization.	Contact support.
`recovery_review`	The task was waiting for funding when we restored service after an incident, and was closed for review. Nothing was held or charged.	Submit a new task.
`input_moderated`	Content safety refused the input. Moderation is always on; see Content moderation.	Change the prompt or media.
`output_moderated`	Content safety refused the result.	Change the prompt or media.
`input_media_invalid`	The model refused a media file when it fetched it: its format, size or length, or its width, height, aspect ratio, pixel count or frame rate.	Check the model's media limits.
`input_media_unreachable`	The model could not fetch a media URL.	Keep the URL reachable until the task closes, or upload the file.
`input_rejected`	The model refused the input for another reason.	Change the input.
`draft_expired`	The draft expired before the final video started.	Generate a new draft.
`provider_unavailable`	The model was temporarily unavailable; the task was canceled.	Submit a new task later.
`delivery_failed`	The result was generated but could not be stored for download.	Submit a new task.
`generation_failed`	Any other failure.	Submit a new task; contact support if it repeats.