排查速查表
| 现象 | 常见方向 | 建议操作 |
|---|---|---|
| 400 或参数校验失败 | 请求格式、上下文或不支持的参数 | 用最小文本请求复现，按协议逐项添加参数 |
| 401 | 密钥缺失、无效、禁用或过期 | 检查变量与认证头，不要打印完整密钥 |
| 403 | 账户、模型、分组或来源限制 | 检查权限和 IP 白名单 |
| 404 或 HTML 页面 | 地址、路径、模型路由 | 检查 Base URL、协议及响应类型 |
| 429 | 请求、Token 或并发限制，也可能是额度错误 | 先看错误正文，再决定等待还是补足额度 |
| 5xx | 网关、上游或临时故障 | 记录请求信息，按有限重试策略处理 |
| 超时或断流 | 网络、长生成、代理缓冲或超时 | 区分连接失败与已开始生成，不盲目重发 |
推荐排查顺序
- 确认最终请求地址指向模型端点，而不是文档站或控制台。
- 用相同密钥查询模型列表，再调用一个确认可用的文本模型。
- 去掉工具、图片、长上下文和可选参数。
- 对照控制台日志，确认请求是否到达及所用分组。
- 最小请求仍失败时，携带脱敏信息联系支持。
不要只判断 HTTP 200
返回可能是任务已提交、工具调用、输出达到限制或流式过程中发生错误。检查完成原因、任务状态和业务必需字段；空文本不一定代表网络错误。
可以提供的排障材料
时间与时区、模型 ID、协议、SDK 版本、状态码、请求 ID、移除密钥的最小复现。排除 Authorization、Cookie、密码、完整用户输入和敏感文件。