KovAPIKovAPI

所有错误的统一格式、每个错误码的含义,以及遇到时该怎么处理。

错误格式

/v1 下的接口出错时,返回 4xx / 5xx 状态码和下面这样的 JSON:message 写给人看,type 是错误大类,code 是稳定的机器可读标识,param 指出出问题的字段(没有时为 null)。请按 HTTP 状态码和 code 判断,不要匹配 message 的文字:它可能是中文、英文或中英双语,措辞也会调整。

HTTP 402 · /v1
{
  "error": {
    "message": "Insufficient balance — please top up",
    "type": "insufficient_quota",
    "code": "insufficient_quota",
    "param": null
  }
}

/anthropic 接口沿用 Anthropic 的格式,没有 code 和 param,按 HTTP 状态码和 error.type 判断:

HTTP 404 · /anthropic
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: gpt-5.5"
  }
}
  • 有的错误会多带几个顶层字段,例如满载时的 attempts、暂时无法处理时的 retry_after。不认识的字段直接忽略即可。
  • 模型方拒绝请求时(例如上下文超长),message 是模型方的原话,code 是模型方给出的值;模型方没有给出时为 invalid_request。

HTTP 状态码速查

HTTP什么时候出现
400参数有误或模型不存在(如 model_not_found),error.param 指出是哪个字段。
401没带 Key,或 Key 无效、已停用(missing_api_key、invalid_api_key)。
402余额不足,或这把 Key 达到了预算上限(insufficient_quota)。
403这把 Key 的模型白名单里没有这个模型,或请求来自这把 Key 的 IP 白名单以外(permission_denied)。
404路径不存在;或任务号不存在、超过了 3 天的保存期、不是这个账号提交的(job_not_found)。
429超过了这把 Key 设置的每分钟请求数或免费模型的每日额度,或者这个模型暂时满载(rate_limit_exceeded)。有 Retry-After 头就按它等待,没有就等几秒再试。
502上游出错或超时,自动重试后仍然失败;code 写明原因,如 upstream_timeout、upstream_unavailable。没有计费,可以重试。
503模型维护中(model_maintenance),或我们这边临时出错(service_unavailable)。没有计费,稍后重试。

全部错误码

按类别列出网关会返回的错误。同一个 HTTP 状态码可能对应多个 code,请以 code 为准。

认证与账号

HTTPcode原因怎么办
401missing_api_key请求没带 Authorization: Bearer 头。/v1 接口不认 x-api-key。加上 Authorization: Bearer YOUR_API_KEY。
401invalid_api_keyKey 不存在、已删除或已停用,或者账号已停用。到控制台「API Keys」页面检查这把 Key。
402insufficient_quota账户余额已经用完(低于透支下限)。充值后重试。
403permission_denied请求来自这把 Key 的 IP 白名单以外。从白名单里的 IP 调用,或在控制台修改白名单。

这把 Key 的限制

HTTPcode原因怎么办
429rate_limit_exceeded超过了这把 Key 设置的每分钟请求数(按最近 60 秒计)。不带 Retry-After。等几秒再试,或在控制台调高这把 Key 的上限。
429rate_limit_exceeded限时免费模型的每日额度用完了(按账号、按 UTC 自然日计)。message 里可能会推荐可以替代的付费模型。UTC 0 点后再用,或改用付费模型。
402insufficient_quota这把 Key 的每日预算(按 UTC 自然日计)或总额度用完了。第二天再用,或在控制台调高额度。
403permission_denied这个模型不在这把 Key 的模型白名单里。换成白名单里的模型,或在控制台修改白名单。

请求本身

HTTPcode原因怎么办
400invalid_json / invalid_encoding请求体不是合法的 JSON;不是 UTF-8 编码时为 invalid_encoding。检查 JSON 语法和编码。
400invalid_request参数不合法:请求体不是 JSON 对象、n 不是整数、参考图或参考视频读不到(message 写明是第几个、什么原因)、/v1/images/edits 没带参考图、视频的时长 / 清晰度 / 比例 / 素材数量超出这个模型的范围等。按 message 修改后重新提交。
400invalid_messages / invalid_role / invalid_max_tokens对话请求的 messages 缺失、为空或格式不对,role 不在允许的范围,或 max_tokens 不是正整数。param 指出是哪个字段。修正 param 指出的字段。
400missing_prompt/v1/images/generations 没有 prompt。补上 prompt。
400unsupported_resolution这个模型不提供所选的分辨率档位(例如 Grok 生图没有 4K)。换一个档位;各模型支持的档位见它的文档。
400invalid_callback_urlcallback_url 不是公网的 http(s) 地址,或超过 2000 个字符。换成能从公网访问的地址。
400max_tokens_too_small思考型模型把 max_tokens 全部用在了思考上,没有写出正文(非流式对话)。调大 max_tokens 后重试。
404not_found接口路径不存在。检查路径,接口列表见 API 手册。
404job_not_found任务号不存在、超过了 3 天的记录保存期,或不是这个账号提交的;拿图片任务号查视频接口(或反过来)也是这个错误。检查任务号和查询接口;结果链接保留 7 天,不受任务记录过期影响。

模型状态

HTTPcode原因怎么办
400model_not_found型号写错、没有传 model,或这个型号不能用在这个接口上(例如拿对话模型调生图接口)。以 GET /v1/models 或 API 手册 里的模型 id 为准。
400model_disabled型号已下架。换用其他型号;有替代型号时,旧型号的页面会自动跳过去。
400model_coming_soon型号已经公布,但还没开放调用。等上线公告。
503model_maintenance型号维护中,暂停接单,期间不会改由其他模型作答。维护结束后重试,进度见 服务状态。

容量与预扣

HTTPcode原因怎么办
402insufficient_quota余额不够预扣这一单。网关先按这一单可能的最高费用预扣,同时发很多请求时也可能出现。如果是并发突发,稍等几秒重试;否则充值。
429rate_limit_exceeded这个模型暂时满载,请求没有发出。只出现在对话类接口:图片和视频任务不会被拒,而是排队。OpenAI 兼容接口带 Retry-After。按 Retry-After 的秒数等待后重试。
503service_unavailable我们这边临时出错,例如保存参考素材失败;/v1/responses 暂时无法处理时也返回 503,并带 Retry-After。稍后重试。

上游出错(对话类接口)

对话类接口(/v1/chat/completions、/v1/responses、/anthropic/v1/messages)出错时,网关会先自动重试,仍然失败才返回下面的错误。这些请求都不计费。

HTTPcode原因怎么办
502upstream_timeout上游超时,包括迟迟没有返回第一个字。重试;长回答建议用 stream: true。
502upstream_unavailable上游出错或暂时不可用。稍后重试。
502upstream_busy模型方限流。模型方的 429 不会原样返回给你,而是换成这个 502。稍后重试。
502upstream_connection_error和模型方的连接中断。重试。
502empty_completion模型方返回了空内容。这不是对你的内容的判定。重试。
502upstream_error上游返回了一句报错,而不是回答。重试。
400content_filter模型处理了请求,但没有给出任何内容,通常是内容触发了模型方的安全策略。调整提示词后重试;原样重试通常还会被拒。
502upstream_prompt_filter提示词被模型方的预检拦截。这不是模型对内容的判定。稍后重试,或稍微调整措辞。
4xx—模型方拒绝了请求(例如上下文超长、参数不支持),状态码和 message 按模型方的原样返回,code 是模型方给出的值。按 message 修改请求。

Anthropic 接口

  • error.type 按状态码取 Anthropic 的标准值:400 invalid_request_error、401 authentication_error、402 billing_error、403 permission_error、404 not_found_error、429 rate_limit_error(模型满载时为 overloaded_error)、502 api_error、503 overloaded_error(模型维护中为 api_error)。
  • /anthropic 只接受 Claude 模型,其他型号返回 404 not_found_error。
  • max_tokens 必填且不能为 0,否则返回 400。

任务失败(图片与视频)

图片和视频任务提交成功后,如果最终失败,查询接口仍然返回 HTTP 200,status 为 failed,原因在 error 里,error.code 是下表中的值;预扣的积分已经全额退回。用 Webhook 时会收到 image.failed / video.failed,内容和查询结果相同。

code什么时候出现怎么办
content_policy视频:提示词、参考素材,或生成的画面 / 声音没通过内容审核(声音被拦时 param 为 audio)。 Wan 标准版和 Prime:输入素材未通过审核。error.reason 为 FaceDetectionSuspect(疑似真人面部)或 DataInspectionFailed(输入内容审核未通过)。error.message 说明原因和调整建议;失败任务未计费。改写提示词或更换素材后再提交;原样重交还会被拒。
request_rejected视频:上游没有接受这次请求,并说明了原因;message 里附上游原话(例如某个参考素材无法处理)。按原话修改提示词或参考素材后再提交;原样重交通常还会失败。不计费。
moderation_blocked图片:模型方的安全审核拒绝了提示词或参考图(也可能是 content_policy_violation)。改写提示词或更换参考图;原样重交通常还会被拒。
render_failed视频:这次没有生成出成片,多为偶发。原样重新提交通常就能成功。
invalid_material视频:上游认为输入素材有问题。这是一个笼统的报错,也常是偶发。先原样重交;反复出现再检查参考素材和提示词长度。
duration_rejected视频:时长没有被接受。最常见的是参考音频或参考视频超过上限,哪怕只超零点几秒。把参考音频 / 视频剪到上限以内再提交;原样重交还会失败。
reference_unreadable视频:模型下载不到参考图、视频或音频,常见是 YouTube、网盘分享页这类网页链接。换成能直接下载到文件的链接,或者在 Playground 本地上传;原样重交还会失败。
render_timeout视频:排队或渲染时间过长,上游放弃了这一单。重新提交。
wait_timeout视频:超过 120 分钟仍未生成结果,按超时处理,积分全额退还;之后如果生成成功,视频免费交付。重新提交。
upstream_unstable视频:渲染过程中连接中断。重新提交。
result_fetch_failed视频已经生成,但我们反复下载或保存成片都没有成功。重新提交。
invalid_request视频:不接受这组参数(例如时长、比例、清晰度的组合)。按 message 调整参数后再提交。
upstream_error其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。通常重新提交就能成功。

异步任务完整说明 →

流式输出中途出错

  • 流式请求一旦返回 HTTP 200 并开始输出,之后的错误不会再改变状态码:要么以一条带 error 的数据出现在流里,要么流直接结束。
  • 判断是否完整:OpenAI 格式看有没有收到 finish_reason 和 data: [DONE],Anthropic 格式看有没有收到 message_stop。没收到就按中断处理。
  • 中断时按断开前已经产生的用量计费,详见 计费与退款。

报错会扣费吗

  • 返回错误的请求一律不扣费:要么在扣费之前就报错,要么预扣的积分全额退回。
  • 失败的图片和视频任务全额退款。
  • 唯一的例外是已经开始输出的流式请求:中途断开时,按断开前已经产生的用量计费。

什么时候重试

4xx 先改请求再发(402 先充值,429 等一会儿);5xx 和超时可以直接重试,间隔用指数退避,有 Retry-After 头就按它等。

重试策略和示例代码 →