# 错误码

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

> https://docs.kovapi.com/zh/guide/errors

## 错误格式

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

```
{
  "error": {
    "message": "Insufficient balance — please top up",
    "type": "insufficient_quota",
    "code": "insufficient_quota",
    "param": null
  }
}
```

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

```
{
  "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` 为准。

### 认证与账号

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

### 这把 Key 的限制

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

### 请求本身

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

### 模型状态

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

### 容量与预扣

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

### 上游出错（对话类接口）

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

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| **502** | `upstream_timeout` | 上游超时，包括迟迟没有返回第一个字。 | 重试；长回答建议用 `stream: true`。 |
| **502** | `upstream_unavailable` | 上游出错或暂时不可用。 | 稍后重试。 |
| **502** | `upstream_busy` | 模型方限流。模型方的 429 不会原样返回给你，而是换成这个 502。 | 稍后重试。 |
| **502** | `upstream_connection_error` | 和模型方的连接中断。 | 重试。 |
| **502** | `empty_completion` | 模型方返回了空内容。这不是对你的内容的判定。 | 重试。 |
| **502** | `upstream_error` | 上游返回了一句报错，而不是回答。 | 重试。 |
| **400** | `content_filter` | 模型处理了请求，但没有给出任何内容，通常是内容触发了模型方的安全策略。 | 调整提示词后重试；原样重试通常还会被拒。 |
| **502** | `upstream_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` 写明具体情况。 | 通常重新提交就能成功。 |

[异步任务完整说明 →](https://docs.kovapi.com/zh/guide/async-jobs)

## 流式输出中途出错

- 流式请求一旦返回 HTTP 200 并开始输出，之后的错误不会再改变状态码：要么以一条带 `error` 的数据出现在流里，要么流直接结束。

- 判断是否完整：OpenAI 格式看有没有收到 `finish_reason` 和 `data: [DONE]`，Anthropic 格式看有没有收到 `message_stop`。没收到就按中断处理。

- 中断时按断开前已经产生的用量计费，详见 [计费与退款](https://docs.kovapi.com/zh/guide/billing)。

## 报错会扣费吗

- 返回错误的请求一律不扣费：要么在扣费之前就报错，要么预扣的积分全额退回。

- 失败的图片和视频任务全额退款。

- 唯一的例外是已经开始输出的流式请求：中途断开时，按断开前已经产生的用量计费。

## 什么时候重试

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

[重试策略和示例代码 →](https://docs.kovapi.com/zh/guide/rate-limits#retry)
