Skip to Content

Errors

Standardized HTTP error envelope, complete request error code table, and asynchronous task failure codes.

Error response shape

Every failed HTTP request returns a real HTTP status code together with a unified JSON error object. Always branch on error.code rather than error.message (messages are English human-readable text and may be refined over time).

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "input.duration",
    "message": "duration must be -1 or between 4 and 30.",
    "request_id": "req_01JD8X9C7M8W2N4K6P1Q3R5S7T",
    "doc_url": "https://kerox.ai/docs/errors#invalid_parameter"
  }
}

Every response also carries the x-request-id header. Include request_id when you contact Support.

Request error codes

Each doc_url returned by the API anchors directly to its row below (#<code>).

CodeHTTPTypeWhen it happens
invalid_json400invalid_request_errorThe request body is not valid JSON, or Content-Type is not application/json.
missing_field400invalid_request_errorA required top-level field such as model or input is missing (see param).
missing_api_key401authentication_errorNo Authorization: Bearer key header was provided.
invalid_api_key401authentication_errorThe API key does not exist or has been revoked.
insufficient_balance402balance_errorAvailable balance is lower than the estimated cost of this task.
negative_balance402balance_errorThe account balance is negative. Top up before submitting new tasks.
account_disabled403permission_errorThe account has been disabled. Contact support for help.
email_not_verified403permission_errorConfirm your account email address before submitting generation tasks: sign in to the Console again with an emailed code.
route_not_found404not_found_errorThe endpoint path or HTTP method does not exist.
model_not_found404not_found_errorThe requested model ID does not exist or is not published.
task_not_found404not_found_errorNo task with this ID exists under your account.
file_not_found404not_found_errorNo uploaded file with this ID exists under your account.
idempotency_conflict409conflict_errorThe same Idempotency-Key was reused with a different request body within 24 hours.
task_not_cancelable409conflict_errorOnly queued tasks can be canceled; this task is already running or finished.
payload_too_large413invalid_request_errorRequest body exceeds 4 MB, or inline base64 data URIs exceed 3 MB total. Upload via POST /v1/files instead.
invalid_parameter422invalid_request_errorA parameter value failed validation (see param for the field path).
unknown_parameter422invalid_request_errorThe model does not recognize this parameter (message suggests the closest valid name).
unified_not_supported422invalid_request_errorThis model does not support format: "unified". Use format: "native".
model_coming_soon422invalid_request_errorThe model is listed in the catalog as coming soon and is not yet open for submissions.
rate_limited429rate_limit_errorMore task submissions or uploads per minute than your account, or your IP address, is allowed. Wait the retry-after seconds before retrying.
concurrency_limited429rate_limit_errorToo many tasks in progress (queued or running). Wait for one to finish, then submit again.
internal_error500api_errorSomething went wrong on our side. Retry with an Idempotency-Key, or contact Support with the request_id.
service_unavailable503api_errorThe service is temporarily unavailable. Retry after a brief backoff.

Task failure codes

When a task is accepted (201) and later fails during generation, GET /v1/tasks/{id} and the task.failed webhook return status: "failed" with error: { code, message, retryable }. Failed tasks are refunded in full (cost.status: "refunded").

CodeWhen it happensRetryable
content_policy_violation
The prompt or an input image/video did not pass content moderation.
The prompt or an input file did not pass content moderation.
No
invalid_input
Parameters passed schema checks, but the model rejected the input (for example unsupported dimensions).
The model could not process this input.
No
input_fetch_failed
An input media URL could not be downloaded or returned a non-2xx response.
An input file URL could not be fetched.
No
generation_failed
Generation failed for an unknown reason. Refunded in full.
Generation failed. Please try again.
Yes
timeout
The task exceeded the model maximum timeout without producing a result.
The task did not finish within the time limit of the model.
Yes
model_unavailable
The model is temporarily unavailable. Retry after a short wait.
The model is temporarily unavailable. Please try again.
Yes
internal_error
An unexpected error occurred while processing the task.
Something went wrong on our side. Please try again.
Yes

On this page

For AI agents

This page as Markdown: /docs/errors.md

Everything at once: /llms-full.txt