# 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).

```json
{
  "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>`).

| HTTP | `type` | `code` | When it happens |
| --- | --- | --- | --- |
| 400 | `invalid_request_error` | `invalid_json` | The request body is not valid JSON, or Content-Type is not application/json. |
| 400 | `invalid_request_error` | `missing_field` | A required top-level field such as model or input is missing (see param). |
| 401 | `authentication_error` | `missing_api_key` | No Authorization: Bearer key header was provided. |
| 401 | `authentication_error` | `invalid_api_key` | The API key does not exist or has been revoked. |
| 402 | `balance_error` | `insufficient_balance` | Available balance is lower than the estimated cost of this task. |
| 402 | `balance_error` | `negative_balance` | The account balance is negative. Top up before submitting new tasks. |
| 403 | `permission_error` | `account_disabled` | The account has been disabled. Contact support for help. |
| 403 | `permission_error` | `email_not_verified` | Confirm your account email address before submitting generation tasks: sign in to the Console again with an emailed code. |
| 404 | `not_found_error` | `route_not_found` | The endpoint path or HTTP method does not exist. |
| 404 | `not_found_error` | `model_not_found` | The requested model ID does not exist or is not published. |
| 404 | `not_found_error` | `task_not_found` | No task with this ID exists under your account. |
| 404 | `not_found_error` | `file_not_found` | No uploaded file with this ID exists under your account. |
| 409 | `conflict_error` | `idempotency_conflict` | The same Idempotency-Key was reused with a different request body within 24 hours. |
| 409 | `conflict_error` | `task_not_cancelable` | Only queued tasks can be canceled; this task is already running or finished. |
| 413 | `invalid_request_error` | `payload_too_large` | Request body exceeds 4 MB, or inline base64 data URIs exceed 3 MB total. Upload via POST /v1/files instead. |
| 422 | `invalid_request_error` | `invalid_parameter` | A parameter value failed validation (see param for the field path). |
| 422 | `invalid_request_error` | `unknown_parameter` | The model does not recognize this parameter (message suggests the closest valid name). |
| 422 | `invalid_request_error` | `unified_not_supported` | This model does not support format: "unified". Use format: "native". |
| 422 | `invalid_request_error` | `model_coming_soon` | The model is listed in the catalog as coming soon and is not yet open for submissions. |
| 429 | `rate_limit_error` | `rate_limited` | More task submissions or uploads per minute than your account, or your IP address, is allowed. Wait the retry-after seconds before retrying. |
| 429 | `rate_limit_error` | `concurrency_limited` | Too many tasks in progress (queued or running). Wait for one to finish, then submit again. |
| 500 | `api_error` | `internal_error` | Something went wrong on our side. Retry with an Idempotency-Key, or contact Support with the request_id. |
| 503 | `api_error` | `service_unavailable` | 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` | `retryable` | When it happens |
| --- | --- | --- |
| `content_policy_violation` | `false` | The prompt or an input image/video did not pass content moderation. |
| `invalid_input` | `false` | Parameters passed schema checks, but the model rejected the input (for example unsupported dimensions). |
| `input_fetch_failed` | `false` | An input media URL could not be downloaded or returned a non-2xx response. |
| `generation_failed` | `true` | Generation failed for an unknown reason. Refunded in full. |
| `timeout` | `true` | The task exceeded the model maximum timeout without producing a result. |
| `model_unavailable` | `true` | The model is temporarily unavailable. Retry after a short wait. |
| `internal_error` | `true` | An unexpected error occurred while processing the task. |
