# TokenPlus 模型调用错误与限流处理

接入示例见 [快速开始](/ai-docs/quickstart.md)，速率概念见 [模型指标](/ai-docs/features.md)。以下只涉及模型 API 调用。

## 排查顺序

1. 核对真实推理端点、协议与 HTTP 方法，不把网站首页地址或管理 API 作为推理地址。
2. 核对 Key 可用性及该 Key 的模型权限；只检查安全存储中的凭据，不在报错材料中公开完整值。
3. 使用完整 model ID，检查 messages、max_tokens、系统提示位置及模型支持的参数/模态。
4. 保存 HTTP 状态、脱敏错误体、响应中的请求标识与发生时间；检查完整响应，而不只看 HTTP 成功头。
5. 比较限额、输入/输出长度和实际负载，再决定是否调整参数或重试。

## 常见情况

| 情况                  | 处理                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| 400 或参数错误        | 检查请求体、模型 ID、协议、支持参数和输入长度，修正后再请求                                       |
| 401                   | 检查 API Key 和认证头；浏览器登录状态不能代替 Key                                                 |
| 403                   | 核对该 Key 对模型及渠道的访问权限，不通过改标识绕过限制                                           |
| insufficient_funds    | 资金不足错误；停止重复生成并处理可用资金问题，不能将所有 402 一律解释为该错误                     |
| 404                   | 核对端点与模型/渠道是否存在，不能自动替换成另一模型并声称调用成功                                 |
| 429                   | 读错误说明及 Retry-After（如果存在），判断请求/Token/并发等限制；不要只凭状态码断言超了哪一种配额 |
| 超时、网络中断、5xx   | 上游可能已执行；先核对可取得的结果，再进行有上限的重试，避免重复费用                              |
| SSE 错误/缺少结束标志 | 保留已收到部分文本但标注响应不完整，不能当作正常完成                                              |

表格是排查指导，不是所有部署均使用的完整错误码契约。应同时读取业务错误标识和原始响应。

## 限流与重试

- RPM 是请求/分钟，TPM 是 Token/分钟，TPS 是生成 Token/秒；不要混用来设置节流器。
- 降低客户端并发、平滑发送节奏，并在提供 Retry-After 时遵循它。
- 退避应有次数/总时间上限，必要时加入抖动；不要对每个错误无条件重试。
- 自动重试可能与 SDK 自带重试叠加，需要一起控制。未确认幂等保证时不能承诺重试不会重复执行或计费。
- 不能由 429 推导统一的限额数值；模型或渠道未公开额度时明确“未提供”。

## 流式响应

Chat 以 `[DONE]`、Messages 以 `message_stop` 为常见正常结束标志，同时需处理其协议中的错误帧。HTTP 200 之后仍可能失败，连接断开也不保证模型正常结束。

重新发起请求会产生另一段生成，不应把两次响应拼接并当成同一次完整成功。停止接收不等于撤销已生成的用量。

## 安全提供排错信息

提供模型 ID、协议、发生时间、请求标识、HTTP 状态和脱敏错误内容即可；不要附 Authorization、x-api-key、Cookie、上游凭据或未经脱敏的业务输入。