# 错误码与请求 ID

URL: http://localhost:3000/docs/zh-cn/errors

对话接口的错误响应格式、计费相关错误码，以及请求 ID 相关的请求头与响应头。



## 请求 ID [#请求-id]

| 头                     | 方向  | 说明                                                   |
| --------------------- | --- | ---------------------------------------------------- |
| `X-Request-ID`        | 响应头 | 平台请求 ID，每个响应都返回。错误响应体中的 `requestId` 与它相同。反馈问题时请提供该值。 |
| `X-Client-Request-ID` | 请求头 | 调用方自定义的请求 ID，可选。去除控制字符后截断到 128 个字符，记入请求日志。           |

* 请求头中的 `X-Request-ID` 会被忽略，不影响平台请求 ID。
* `X-Client-Request-ID` 可在控制台请求日志中按原值精确查询，账单导出的模型调用行带「客户请求ID」列。
* `X-Client-Request-ID` 不要求唯一，也不是幂等键：用相同的值重试会产生多次调用，并分别计费。

## 错误响应格式 [#错误响应格式]

`POST /api/v1/chat/completions` 的错误响应体：

```json
{
  "requestId": "req_0192f3a1-c2d3-7e5f-8a9b-0c1d2e3f4a5b",
  "error": "InsufficientCredits",
  "errorCode": 10505,
  "message": "insufficient credits",
  "detail": {}
}
```

| 字段          | 说明                           |
| ----------- | ---------------------------- |
| `requestId` | 平台请求 ID，同响应头 `X-Request-ID`。 |
| `error`     | 错误名称。                        |
| `errorCode` | 数字错误码，按它分支处理。                |
| `message`   | 错误描述，仅供排查，内容可能调整。            |
| `detail`    | 附加信息，可能为空对象。                 |

## 计费相关错误 [#计费相关错误]

请求在调用模型前先按额度预留，以下错误均在调用模型前返回，不产生费用。

| HTTP 状态码 | `error`                   | `errorCode` | 含义                                                                              | 处理                               |
| -------- | ------------------------- | ----------- | ------------------------------------------------------------------------------- | -------------------------------- |
| 402      | `InsufficientCredits`     | 10505       | 租户可用余额不足，或租户已欠费                                                                 | 充值后重试                            |
| 402      | `MembershipQuotaExceeded` | 10506       | 发起人的成员额度不足                                                                      | 由租户管理员调整成员额度                     |
| 402      | `APIKeyQuotaExceeded`     | 10507       | API Key 的额度不足                                                                   | 调整该 API Key 的额度                  |
| 503      | `FailedPrecondition`      | 50301       | 计费准入暂时不可用，`detail.reason` 为 `billing_admission_unavailable` 或 `budget_exceeded` | 按响应头 `Retry-After` 的秒数（当前为 1）后重试 |

* 402 不带 `Retry-After`，额度恢复前重试会得到同样的结果。
* 预留额随输出上限增长。余额或额度接近用尽时，调小请求中的 `max_tokens` / `max_completion_tokens` 可能使请求通过。
* 租户余额为负（已欠费）期间，新请求一律返回 402 `InsufficientCredits`；充值会先抵扣欠费。
* 计费准入不返回 429。429 仅表示触发了速率限制。