故障排查
先记录 HTTP 状态码、请求时间、接口路径、模型 ID 和脱敏响应，再按下表排查。
| 现象 | 优先检查 | 处理 |
|---|---|---|
401 | API Key 缺失、错误或已停用 | 确认认证头，重新创建独立密钥 |
403 | 密钥权限、IP 限制或模型范围 | 核对请求来源和密钥限制 |
404 | Base URL 或路径错误 | 检查是否缺少或重复 /v1 |
429 | 频率、并发、余额或额度限制 | 降低并发，检查余额和密钥额度 |
5xx | 短时上游或网络异常 | 保留时间和请求信息，避免无限重试 |
| 返回 HTML | 请求到了主站页面 | 填写正确 API 路径，不要使用文档域名 |
| 模型不存在 | 模型 ID 过期或无权限 | 重新读取 GET /v1/models |
请求超时
- 先用短文本、非流式请求验证连通性。
- 降低输出上限，暂停工具调用和大文件。
- 检查客户端代理、VPN 和超时设置。
- 不要对
504或524立即无限重试，原请求可能已被上游处理并产生计费。
客户端仍访问旧地址
- 完全退出客户端后重新打开；
- 检查是否同时存在全局、项目级和 CC Switch 多份配置；
- 检查路径中是否出现
/v1/v1/； - 通过控制台日志确认实际请求是否到达云筑Hub。
仍无法解决时，参阅获取帮助准备脱敏信息。