*更新日期: 2026-11-07*

# 错误码

所有 `/v1` 错误都是同一形状：

```json
{
  "error": {
    "message": "Model seedream-x is not available",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `error.message` | string | 可读说明，可能改文案，不要当稳定契约 |
| `error.type` | string | OpenAI 风格分类：`authentication_error` / `rate_limit_error` / `invalid_request_error` / `api_error` |
| `error.param` | string \| null | 出错字段，例如 `model`、`id` |
| `error.code` | string | 业务逻辑看这个 |

业务逻辑看 `code`。响应**不包含** `Retry-After`。

| code | HTTP | type | 何时 |
|------|------|------|------|
| `invalid_api_key` | 401 | authentication_error | 缺 Key、错 Key、已吊销、租户停用 |
| `insufficient_quota` | 429 | rate_limit_error | 余额不足且方法不是 GET（`/v1/sub-accounts` 管理面除外）。`GET /v1/balance` 在余额为 0 时仍是 200，`balance` 为 `"0.00"` |
| `management_forbidden` | 403 | invalid_request_error | 用子账户 Key 调用 `/v1/sub-accounts` 管理接口 |
| `rate_limit_exceeded` | 429 | rate_limit_error | 该 Key 该能力超过 RPM |
| `invalid_request` | 400 | invalid_request_error | 请求体校验失败（缺字段、类型不对） |
| `model_not_found` | 404 | invalid_request_error | 模型不可用；任务不存在；视频未完成时取 content |
| `capability_not_enabled` | 400 | invalid_request_error | 模型能力与路径不符，或该能力未实现 |
| `upstream_error` | 502 | api_error | 模型服务失败或转存失败；不透出原始错误细节 |
| `upstream_unavailable` | 503 / 400 | api_error 或 invalid_request_error | 服务暂不可用，或当前无法完成请求 |
| `gateway_timeout` | 504 | api_error | 网关等待模型服务超时，未扣费 |
| `content_policy_violation` | 400 | invalid_request_error | 内容策略拒绝（若映射到此码）；多数情况下仍表现为 `upstream_error` |

## 对话流里的错误

`stream: true` 时，模型调用失败可能仍是 HTTP 200。事件流里会出现：

```
data: {"error":{"message":"模型服务请求失败","type":"api_error","param":null,"code":"upstream_error"}}

data: [DONE]
```

解析 SSE 时先看有没有 `error`，再拼 `delta.content`。

## 转存失败

图/视频生成成功但对象存储写入失败时，对外仍是 `upstream_error`，`message` 为「转存失败」，不会把临时链接交给你。视频模型关闭产物转存时不走对象存储，会直接返回上游地址；若无法安全直出则自动回退转存。

> **重试**
>
> `gateway_timeout`、偶发 `upstream_error` 可以有限重试。`invalid_api_key`、`invalid_request`、`model_not_found`、`capability_not_enabled` 重试无意义。`insufficient_quota` 要等充值。`rate_limit_exceeded` 等下一自然分钟窗口。
