文档目录
TROUBLESHOOTING
从状态码定位问题
先确认请求是否完整到达，再区分鉴权、权限、限流和上游错误。下面的顺序可以减少无效重试，也更容易保留诊断证据。
五步快速检查
确认 Base URL
应为 https://www.tokensupply.net/v1，避免重复拼出 /v1/v1。
确认 API Key
使用 Bearer 请求头，检查 Key 是否启用、是否过期及是否分配了分组。
查询模型列表
用同一枚 Key 调用 GET /v1/models，并原样使用返回的模型 ID。
缩小请求
用最短非流式请求排除工具调用、长上下文和客户端流处理问题。
记录诊断信息
保存发生时间、HTTP 状态码、响应错误和请求标识；密钥只保留末四位。
常见 HTTP 状态码
400请求无效检查 JSON、必填的
model、stream 类型和请求体是否被中途截断。401鉴权失败确认 Bearer Key 正确、完整且仍然有效。不要用 URL 查询参数传 Key。
403权限或余额检查余额、Key 分组、模型权限、Key 状态和分组限制；不要把所有 403 都当成密钥错误。
426需要升级协议请求进入 WebSocket GET 入口但未 Upgrade。普通调用改用 POST，或关闭客户端 WebSocket。
429限流或容量尊重服务返回的等待信息，使用指数退避和随机抖动；不要立即并发重试。
5xx服务或上游异常短暂等待后有限重试。持续出现时保留请求标识、时间和模型，交给支持人员定位。
请求体读取或解析失败
Failed to read request body
服务没有读到一个完整请求体。常见原因是客户端主动取消、网络中断、代理提前关闭上传连接，或发送内容超过服务允许的大小。这与 JSON 语法错误不是同一件事。
Request body is empty
请求没有正文。确认请求方法是 POST、请求库确实写入 body，并设置了 Content-Type: application/json。
Failed to parse request body
正文已到达，但不是有效 JSON。重点检查尾随逗号、引号、转义字符，以及命令行 shell 对 JSON 的二次解析。
先用最小 cURL 验证如果最小请求成功，故障通常在原客户端、代理、请求生成或超时配置，而不是 API Key 与模型本身。
流式输出中断
- 确保代理没有缓冲 SSE，并允许足够长的读取时间。
- 客户端应持续消费响应；暂停读取可能产生背压或触发超时。
- 用户主动停止生成会取消请求，服务端可能记录 context canceled，这通常不是平台故障。
- 在收到首个流事件后，后续错误可能位于事件流内；不要只检查初始 HTTP 200。
若流式失败但非流式成功，先检查客户端事件解析、代理缓冲和超时。不要用无限重试掩盖持续性错误。
安全重试策略
| 错误类型 | 是否重试 | 建议 |
|---|---|---|
| 400 / 401 / 403 / 426 | 修正后再试 | 配置或请求不会因等待而自行恢复，直接重复只会制造更多失败。 |
| 429 | 可以 | 指数退避并加入随机抖动，限制总次数和并发量。 |
| 502 / 503 / 504 | 可以 | 仅对可安全重复的请求进行有限重试，并保留最终错误。 |
| 流已输出部分内容 | 谨慎 | 重试可能产生重复输出或重复副作用，需要由业务层去重。 |
不要重试所有错误鉴权、余额、模型权限和无效 JSON 必须先修正。对这些错误自动重试会放大负载，也可能触发额外限制。
提交有效的故障信息
联系支持时提供：发生时间和时区、接口路径、模型 ID、HTTP 状态码、完整错误文本、客户端名称与版本，以及请求标识。API Key 仅提供末四位，输入内容先删除敏感数据。
绝不发送完整密钥聊天记录、截图和工单都不是存放 API Key 的位置。怀疑泄露时立即禁用旧 Key 并创建新 Key。