# 错误码

> 统一的 HTTP 错误响应格式、全部请求错误码表以及异步任务失败错误码。

## 错误响应结构

所有请求错误都会返回真实的 HTTP 状态码以及统一的 JSON 错误对象。程序逻辑请始终依据 `error.code` 判断，不要解析 `error.message`（英文提示语可能会微调）。

```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"
  }
}
```

每个响应同时附带 `x-request-id` 响应头，提交工单排查问题时请一并提供 `request_id`。

## 请求错误码

接口返回的 `doc_url` 会直接锚定到下表中对应的错误码行（`#<code>`）。

| HTTP | `type` | `code` | 触发场景 |
| --- | --- | --- | --- |
| 400 | `invalid_request_error` | `invalid_json` | 请求体不是合法 JSON，或 Content-Type 不是 application/json。 |
| 400 | `invalid_request_error` | `missing_field` | 缺少 model 或 input 等必填外壳字段（具体字段见 param）。 |
| 401 | `authentication_error` | `missing_api_key` | 未提供 Authorization: Bearer API Key 请求头。 |
| 401 | `authentication_error` | `invalid_api_key` | API Key 不存在或已被吊销。 |
| 402 | `balance_error` | `insufficient_balance` | 可用余额不足以覆盖本次任务的预估费用。 |
| 402 | `balance_error` | `negative_balance` | 账户余额为负，请先充值后再提交新任务。 |
| 403 | `permission_error` | `account_disabled` | 账户已被停用，如有疑问请联系我们。 |
| 403 | `permission_error` | `email_not_verified` | 邮箱尚未确认，请用邮箱验证码重新登录一次控制台，再提交任务。 |
| 404 | `not_found_error` | `route_not_found` | 接口路径不存在或 HTTP 方法不正确。 |
| 404 | `not_found_error` | `model_not_found` | 指定的模型 ID 不存在或尚未上架。 |
| 404 | `not_found_error` | `task_not_found` | 当前账户下找不到对应 ID 的任务。 |
| 404 | `not_found_error` | `file_not_found` | 当前账户下找不到对应 ID 的上传文件。 |
| 409 | `conflict_error` | `idempotency_conflict` | 24 小时内使用相同的 Idempotency-Key 发送了不同内容的请求体。 |
| 409 | `conflict_error` | `task_not_cancelable` | 只有排队中（queued）的任务可以取消；该任务已开始运行或已结束。 |
| 413 | `invalid_request_error` | `payload_too_large` | 请求体超过 4 MB，或内联 base64 文件总计超过 3 MB，请改用 POST /v1/files 上传。 |
| 422 | `invalid_request_error` | `invalid_parameter` | 参数取值不合法（具体字段路径见 param）。 |
| 422 | `invalid_request_error` | `unknown_parameter` | 模型不识别该参数（message 中会提示最接近的正确参数名）。 |
| 422 | `invalid_request_error` | `unified_not_supported` | 该模型不支持 unified 统一格式，请使用 native 原厂格式。 |
| 422 | `invalid_request_error` | `model_coming_soon` | 该模型当前处于即将上线状态，暂未开放任务提交。 |
| 429 | `rate_limit_error` | `rate_limited` | 超过账户或来源 IP 的每分钟提交或上传次数，请等待 retry-after 响应头指定的秒数后重试。 |
| 429 | `rate_limit_error` | `concurrency_limited` | 进行中的任务数（排队中或生成中）已到上限，等有任务结束后再提交。 |
| 500 | `api_error` | `internal_error` | 我们这边出了问题。请带上 Idempotency-Key 重试，或带上 request_id 提交工单。 |
| 503 | `api_error` | `service_unavailable` | 服务暂时不可用，请退避后重试。 |

## 任务失败错误码

当任务提交成功（`201`）但在生成过程中失败时，`GET /v1/tasks/{id}` 与 `task.failed` Webhook 会返回 `status: "failed"` 以及 `error: { code, message, retryable }`。失败的任务一律全额退回（`cost.status: "refunded"`）。

| `code` | `retryable` | 触发场景 |
| --- | --- | --- |
| `content_policy_violation` | `false` | 提示词或输入的图片/视频未通过内容审核。 |
| `invalid_input` | `false` | 参数通过了基础校验，但模型执行时拒绝了输入（如图片尺寸不符合要求）。 |
| `input_fetch_failed` | `false` | 输入的文件 URL 无法访问或下载失败。 |
| `generation_failed` | `true` | 生成失败，原因不明。已全额退回。 |
| `timeout` | `true` | 任务超过模型最长等待时间仍未返回结果。 |
| `model_unavailable` | `true` | 模型暂时不可用，请稍后重试。 |
| `internal_error` | `true` | 任务处理过程中发生服务端内部错误。 |
