错误码、限流与重试

响应格式

错误统一返回：

{
  "error": {
    "message": "Invalid token (request id: 2026...)",
    "type": "new_api_error",
    "code": ""
  }
}

request id 一定要保留：排查与对账时它能精确定位到那一次请求。

HTTP 状态与典型原因

状态	含义	常见原因	建议
400	请求不合法	缺字段、类型错误、模型不支持该参数	按报错字段修正
401	鉴权失败	Key 拼错/被禁用/被删除	换有效 Key
403	无权限	Key 无该模型权限；realname_required；temp_blacklisted	见下表专属 code
404	路径或模型不存在	URL 写错；模型未开放	用 /v1/models 核对
429	触发限流	请求过密；channel_capacity_exceeded	退避重试
5xx	上游或平台异常	上游超时/5xx	指数退避 + 带 request id 反馈

平台特有错误码

code	触发条件	处理
realname_required	调用需实名模型但账号未实名	到「实名认证」提交并通过审核（最长 30 秒生效）
temp_blacklisted	来源 IP 或账号被平台临时限制	联系支持确认原因；到期自动解除
channel_capacity_exceeded	目标渠道达到 RPM/TPM/并发上限	稍后重试；响应里带 reason（rpm/tpm/concurrent）与渠道号
AUTH_SESSION_LIMIT / AUTH_SESSION_ISSUANCE_LIMIT	账号活跃会话/发放次数超限	退出多余登录设备后重试

限流口径

平台有三层保护，都不消耗上游（在请求入口或选路后立即拒绝）：

1. 模型请求速率限制：按令牌统计的 RPM（是否开启与阈值以平台配置为准，默认策略为 5 次/分钟）。
2. 渠道容量保护：单条渠道的 RPM/TPM/并发上限，达到上限返回 429。
3. 临时黑名单：按 IP/IP 段/账号临时封禁，命中返回 403 temp_blacklisted。

重试建议

契约验证：无效 Key 必须是 401

code=$(curl -s -o /dev/null -w '%{http_code}' \
  "${HEIMA_BASE_URL:-https://api.token.heimatianqi.com/v1}/chat/completions" \
  -H "Authorization: Bearer sk-invalid-key-for-docs" \
  -H "Content-Type: application/json" \
  -d '{"model":"mock-chat","messages":[{"role":"user","content":"x"}]}')
python3 -c "import sys; assert sys.argv[1] == '401', 'expected 401, got ' + sys.argv[1]; print('invalid key ->', sys.argv[1])" "$code"

这条断言保证"密钥无效"不会被误报成 5xx 或 403，客户端才能据此区分「换 Key」与「重试」。

• 对 429 / 5xx 使用指数退避（例如 0.5s → 1s → 2s，最多 3 次）。
• 对 400 / 401 / 403 不要重试：参数或权限问题重试只会浪费配额。
• 流式请求中途断开时，已经产生的 tokens 仍会按实际用量计费（可在使用日志里核对）。

常见问题

• 为什么我什么都没改，突然 403 了？ 看 code：realname_required 是门槛， temp_blacklisted 是平台侧临时限制；两者都会在错误体里说明。
• 能提高限流阈值吗？ 可以联系支持调整，平台会结合你的用量与渠道容量评估。