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>).
| Code | HTTP | Type | When it happens |
|---|---|---|---|
| invalid_json | 400 | invalid_request_error | The request body is not valid JSON, or Content-Type is not application/json. |
| missing_field | 400 | invalid_request_error | A required top-level field such as model or input is missing (see param). |
| missing_api_key | 401 | authentication_error | No Authorization: Bearer key header was provided. |
| invalid_api_key | 401 | authentication_error | The API key does not exist or has been revoked. |
| insufficient_balance | 402 | balance_error | Available balance is lower than the estimated cost of this task. |
| negative_balance | 402 | balance_error | The account balance is negative. Top up before submitting new tasks. |
| account_disabled | 403 | permission_error | The account has been disabled. Contact support for help. |
| email_not_verified | 403 | permission_error | Confirm your account email address before submitting generation tasks: sign in to the Console again with an emailed code. |
| route_not_found | 404 | not_found_error | The endpoint path or HTTP method does not exist. |
| model_not_found | 404 | not_found_error | The requested model ID does not exist or is not published. |
| task_not_found | 404 | not_found_error | No task with this ID exists under your account. |
| file_not_found | 404 | not_found_error | No uploaded file with this ID exists under your account. |
| idempotency_conflict | 409 | conflict_error | The same Idempotency-Key was reused with a different request body within 24 hours. |
| task_not_cancelable | 409 | conflict_error | Only queued tasks can be canceled; this task is already running or finished. |
| payload_too_large | 413 | invalid_request_error | Request body exceeds 4 MB, or inline base64 data URIs exceed 3 MB total. Upload via POST /v1/files instead. |
| invalid_parameter | 422 | invalid_request_error | A parameter value failed validation (see param for the field path). |
| unknown_parameter | 422 | invalid_request_error | The model does not recognize this parameter (message suggests the closest valid name). |
| unified_not_supported | 422 | invalid_request_error | This model does not support format: "unified". Use format: "native". |
| model_coming_soon | 422 | invalid_request_error | The model is listed in the catalog as coming soon and is not yet open for submissions. |
| rate_limited | 429 | rate_limit_error | More task submissions or uploads per minute than your account, or your IP address, is allowed. Wait the retry-after seconds before retrying. |
| concurrency_limited | 429 | rate_limit_error | Too many tasks in progress (queued or running). Wait for one to finish, then submit again. |
| internal_error | 500 | api_error | Something went wrong on our side. Retry with an Idempotency-Key, or contact Support with the request_id. |
| service_unavailable | 503 | api_error | The 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").
| Code | When it happens | Retryable |
|---|---|---|
| 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 |