按现象缩小范围
| 现象 | 优先核对 | 下一步 |
|---|---|---|
| 401 / 403 | 密钥空格、失效、账号与模型权限 | 重新核对配置，不在日志中打印密钥。 |
| 404 / 模型不存在 | Base URL、完整端点、准确模型 ID | 比较快速开始示例与实际请求。 |
| 429 | 错误正文、5 小时 / 周额度、并发或上游限流 | 按控制台或 Retry-After 提示等待；额度耗尽与瞬时拥堵分开处理。 |
| 5xx / 超时 | 请求标识、时间、上游错误、网络与客户端超时 | 有限次数重试，记录每次结果与用量。 |
| HTTP 200 但回答截断 | 流式错误事件、结束标记、断线与超时 | 核对完整事件序列，不能仅凭 200 判断成功。 |
重试与切换模型
可恢复的网络或临时服务错误可采用有上限的退避重试。鉴权失败、模型无权限或明确额度耗尽时，先修正配置或等待恢复。请求超时并不一定代表上游没有处理，请检查用量记录后再批量重发。
切换模型前确认它在当前账号可用范围内。一个模型失败不能证明其他模型一定可用，也不能仅凭升级套餐推断所有上游错误都会消失。
提交哪些排查信息
- 发生时间与时区、客户端名称和版本。
- 模型 ID、接口路径、是否使用流式。
- HTTP 状态、错误正文及请求标识；删除密钥、手机号和私人对话内容。
- 控制台额度状态，以及独立最小请求是否出现相同错误。