Skip to Content

错误码

统一的 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_json400invalid_request_error请求体不是合法 JSON,或 Content-Type 不是 application/json。
missing_field400invalid_request_error缺少 model 或 input 等必填外壳字段(具体字段见 param)。
missing_api_key401authentication_error未提供 Authorization: Bearer API Key 请求头。
invalid_api_key401authentication_errorAPI Key 不存在或已被吊销。
insufficient_balance402balance_error可用余额不足以覆盖本次任务的预估费用。
negative_balance402balance_error账户余额为负,请先充值后再提交新任务。
account_disabled403permission_error账户已被停用,如有疑问请联系我们。
email_not_verified403permission_error邮箱尚未确认,请用邮箱验证码重新登录一次控制台,再提交任务。
route_not_found404not_found_error接口路径不存在或 HTTP 方法不正确。
model_not_found404not_found_error指定的模型 ID 不存在或尚未上架。
task_not_found404not_found_error当前账户下找不到对应 ID 的任务。
file_not_found404not_found_error当前账户下找不到对应 ID 的上传文件。
idempotency_conflict409conflict_error24 小时内使用相同的 Idempotency-Key 发送了不同内容的请求体。
task_not_cancelable409conflict_error只有排队中(queued)的任务可以取消;该任务已开始运行或已结束。
payload_too_large413invalid_request_error请求体超过 4 MB,或内联 base64 文件总计超过 3 MB,请改用 POST /v1/files 上传。
invalid_parameter422invalid_request_error参数取值不合法(具体字段路径见 param)。
unknown_parameter422invalid_request_error模型不识别该参数(message 中会提示最接近的正确参数名)。
unified_not_supported422invalid_request_error该模型不支持 unified 统一格式,请使用 native 原厂格式。
model_coming_soon422invalid_request_error该模型当前处于即将上线状态,暂未开放任务提交。
rate_limited429rate_limit_error超过账户或来源 IP 的每分钟提交或上传次数,请等待 retry-after 响应头指定的秒数后重试。
concurrency_limited429rate_limit_error进行中的任务数(排队中或生成中)已到上限,等有任务结束后再提交。
internal_error500api_error我们这边出了问题。请带上 Idempotency-Key 重试,或带上 request_id 提交工单。
service_unavailable503api_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.
是

On this page

给 AI 用

本页 Markdown: /zh/docs/errors.md

全部文档合集: /llms-full.txt