排障手册
遇到问题按下面的顺序定位，不要先改代码。
第一步：请求到平台了吗
打开控制台 →「使用日志」，按时间/模型过滤：
- 有这条记录 → 请求已到平台，问题在上游或业务侧（继续第二步）。
- 没有记录 → 请求没到平台：检查 Base URL、Key、网络与代理（继续第四步）。
第二步：看这条日志的细节
展开日志的「日志详情 / 计费过程 / 请求路径」：
| 现象 | 可能原因 |
|---|---|
| 计费过程里出现高峰倍率 | 处在高峰时段，费用正常上浮 |
| 备注里出现「限免/折扣活动」 | 命中了活动，实扣已让利 |
| 请求路径里渠道与预期不同 | 你在「智能路由」里配置了策略，或平台默认选路 |
| 有重试次数 | 上游曾失败，平台自动重试过 |
第三步：对上游错误分类
| 错误 | 处理 |
|---|---|
| 400 | 参数问题：用 /v1/models 确认模型名，检查 messages 结构与可选参数是否被该模型支持 |
| 401 | Key 问题：重新复制或新建 Key |
403 realname_required |
到「实名认证」提交并通过审核 |
403 temp_blacklisted |
平台侧临时限制：联系支持确认原因 |
| 429 | 限流：加指数退避；channel_capacity_exceeded 表示渠道容量已满 |
| 5xx | 上游异常：退避重试；持续失败请把 request id 提供给支持 |
第四步：确认调用姿势
- Base URL 必须是
https://api.token.heimatianqi.com/v1（以/v1结尾）。 - 鉴权头是
Authorization: Bearer sk-heima-...。 - 用 curl 做最小复现：
code=$(curl -s -o /dev/null -w '%{http_code}' \
"${HEIMA_BASE_URL:-https://api.token.heimatianqi.com/v1}/models" \
-H "Authorization: Bearer $HEIMA_API_KEY")
python3 -c "import sys; assert sys.argv[1] == '200', 'expected 200, got ' + sys.argv[1]; print('auth ok ->', sys.argv[1])" "$code"
能返回 200 说明地址 + Key 都对，问题在请求体或模型选择。
第五步：还是不行就带上证据
联系支持时请提供：
- request id（错误响应或使用日志里都有）；
- 时间点与模型名；
- 最小复现请求（Key 请打码）；
- 期望行为与实际现象。