Troubleshooting
排障、重试与安全检查
先确定失败发生在控制台登录、Key 管理、计费，还是模型网关。保留 request_id、时间和状态，但不要提交完整 Key。
先确认控制台登录、Key、余额和模型列表，再用 cURL 发送最小请求。成功时检查客户端配置；失败时按 HTTP 状态和用量记录定位。
- 第一步
- 确认当前配置
- 最小测试
- cURL
- 关联字段
- request_id
- 禁止提交
- 完整 API Key
推荐诊断顺序
- 1确认控制台可以正常登录。
- 2确认 API Key 可用，并核对控制台中的余额与账户状态。
- 3重新复制 Gateway、Key 和模型 ID。
- 4调用 GET /v1/models 验证认证。
- 5用本文档 cURL 发送最小非流式请求。
- 6再把同样配置迁回 SDK、CLI 或 IDE。
模型请求错误矩阵
| 现象 | 优先检查 |
|---|---|
| 400 | JSON、字段类型、必填字段和模型参数 |
| 401 | Key 是否完整、有效以及认证 Header |
| 402 / 403 | 余额、账户或分组权限 |
| 404 | Gateway 地址、/v1 路径、模型目录与协议 |
| 429 | Retry-After、并发、短时间请求量和上游容量 |
| 5xx / timeout | 网关可达性、上游临时故障和客户端超时 |
登录失败
- 确认使用的是登录页当前提供的认证方式。
- 按页面提示完成验证码或安全校验。
- 会话过期时重新登录。
- 注册失败时根据页面提示切换到登录或其他可用方式。
- 账户受限时联系运营处理。
账户与计费问题
| 现象 | 处理 |
|---|---|
| 余额未更新 | 刷新控制台，并核对当前购买记录 |
| 购买入口不可用 | 以控制台当前配置和账户权限为准 |
| 模型调用被拒绝 | 检查余额、Key、模型和分组权限 |
| 记录不一致 | 保留时间和页面记录，联系运营核对 |
API Key 问题
- 无法创建：检查页面校验、账户状态和权限。
- 401：重新复制完整 Key 并确认认证 Header。
- 新 Key 未生效：更新 Secret 并重启缓存凭据的客户端。
- 准备删除 Key 前确认没有客户端仍在使用。
- 持续失败时保留时间、错误码和 request_id。
流式连接与重试
- 代理和客户端读取超时应覆盖模型首 Token 与长响应耗时。
- 使用支持 SSE/streaming 的反向代理配置，关闭不必要的响应缓冲。
- 客户端取消时传播 AbortSignal 或关闭连接。
- 只对 429、明确的临时 5xx 或网络失败做有限指数退避。
- 已开始返回内容的请求不要自动从头重试，除非应用能去重并接受额外费用。
提交排障信息
| 可以提供 | 不要提供 |
|---|---|
| UTC 时间、request_id、相关记录 ID、HTTP 状态 | 完整 API Key 或账户密码 |
| Gateway 域名和路径（不含查询凭据） | Authorization、x-api-key Header |
| 模型 ID、客户端与版本、最小复现步骤 | 敏感 Prompt、完整响应或个人数据 |
| 脱敏后的错误 type/code | 内部管理凭据 |