错误码
统一的 HTTP 错误响应格式、全部请求错误码表以及异步任务失败错误码。
错误响应结构
所有请求错误都会返回真实的 HTTP 状态码以及统一的 JSON 错误对象。程序逻辑请始终依据 error.code 判断,不要解析 error.message(英文提示语可能会微调)。
{
"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 | 类型 | 触发场景 |
|---|---|---|---|
| invalid_json | 400 | invalid_request_error | 请求体不是合法 JSON,或 Content-Type 不是 application/json。 |
| missing_field | 400 | invalid_request_error | 缺少 model 或 input 等必填外壳字段(具体字段见 param)。 |
| missing_api_key | 401 | authentication_error | 未提供 Authorization: Bearer API Key 请求头。 |
| invalid_api_key | 401 | authentication_error | API Key 不存在或已被吊销。 |
| insufficient_balance | 402 | balance_error | 可用余额不足以覆盖本次任务的预估费用。 |
| negative_balance | 402 | balance_error | 账户余额为负,请先充值后再提交新任务。 |
| account_disabled | 403 | permission_error | 账户已被停用,如有疑问请联系我们。 |
| email_not_verified | 403 | permission_error | 邮箱尚未确认,请用邮箱验证码重新登录一次控制台,再提交任务。 |
| route_not_found | 404 | not_found_error | 接口路径不存在或 HTTP 方法不正确。 |
| model_not_found | 404 | not_found_error | 指定的模型 ID 不存在或尚未上架。 |
| task_not_found | 404 | not_found_error | 当前账户下找不到对应 ID 的任务。 |
| file_not_found | 404 | not_found_error | 当前账户下找不到对应 ID 的上传文件。 |
| idempotency_conflict | 409 | conflict_error | 24 小时内使用相同的 Idempotency-Key 发送了不同内容的请求体。 |
| task_not_cancelable | 409 | conflict_error | 只有排队中(queued)的任务可以取消;该任务已开始运行或已结束。 |
| payload_too_large | 413 | invalid_request_error | 请求体超过 4 MB,或内联 base64 文件总计超过 3 MB,请改用 POST /v1/files 上传。 |
| invalid_parameter | 422 | invalid_request_error | 参数取值不合法(具体字段路径见 param)。 |
| unknown_parameter | 422 | invalid_request_error | 模型不识别该参数(message 中会提示最接近的正确参数名)。 |
| unified_not_supported | 422 | invalid_request_error | 该模型不支持 unified 统一格式,请使用 native 原厂格式。 |
| model_coming_soon | 422 | invalid_request_error | 该模型当前处于即将上线状态,暂未开放任务提交。 |
| rate_limited | 429 | rate_limit_error | 超过账户或来源 IP 的每分钟提交或上传次数,请等待 retry-after 响应头指定的秒数后重试。 |
| concurrency_limited | 429 | rate_limit_error | 进行中的任务数(排队中或生成中)已到上限,等有任务结束后再提交。 |
| internal_error | 500 | api_error | 我们这边出了问题。请带上 Idempotency-Key 重试,或带上 request_id 提交工单。 |
| service_unavailable | 503 | api_error | 服务暂时不可用,请退避后重试。 |
任务失败错误码
当任务提交成功(201)但在生成过程中失败时,GET /v1/tasks/{id} 与 task.failed Webhook 会返回 status: "failed" 以及 error: { code, message, retryable }。失败的任务一律全额退回(cost.status: "refunded")。
| 错误码 | 触发场景 | 可重试 |
|---|---|---|
| content_policy_violation | 提示词或输入的图片/视频未通过内容审核。 The prompt or an input file did not pass content moderation. | 否 |
| invalid_input | 参数通过了基础校验,但模型执行时拒绝了输入(如图片尺寸不符合要求)。 The model could not process this input. | 否 |
| input_fetch_failed | 输入的文件 URL 无法访问或下载失败。 An input file URL could not be fetched. | 否 |
| generation_failed | 生成失败,原因不明。已全额退回。 Generation failed. Please try again. | 是 |
| timeout | 任务超过模型最长等待时间仍未返回结果。 The task did not finish within the time limit of the model. | 是 |
| model_unavailable | 模型暂时不可用,请稍后重试。 The model is temporarily unavailable. Please try again. | 是 |
| internal_error | 任务处理过程中发生服务端内部错误。 Something went wrong on our side. Please try again. | 是 |