常见问题与排障

401 Unauthorized

• Key 不完整、已删除或过期；
• 请求头格式错误；
• 把管理员登录 Token 当成了 API Key。

正确的 OpenAI 请求头：

Authorization: Bearer sk-your-key

403 Forbidden

• Key 存在 IP 白名单/黑名单；
• 分组限制客户端类型；
• 用户或 Key 被禁用；
• 当前协议不允许调度到该分组。

404 Not Found

重点检查 Base URL 是否重复拼接：

错误：https://api.minoagi.com/v1/responses/v1/responses
正确：https://api.minoagi.com/v1/responses

不要把 /home、/login 或文档地址作为 API Base URL。

429 Too Many Requests

• 用户并发、Key 并发或上游并发达到上限；
• RPM/TPM 限制触发；
• 上游账号进入限流窗口。

降低并发并等待后重试。不要进行高频无退避重试。

5xx 或上游不可用

• 当前分组没有健康账号；
• 上游账号过期、封禁或配额耗尽；
• 代理网络异常；
• 上游返回格式异常。

记录请求时间、模型、状态码和 x-request-id，再联系管理员排查。不要发送完整 API Key。

客户端仍访问官方地址

• 完全关闭并重新打开终端或客户端；
• 检查环境变量是否在启动客户端的同一终端生效；
• CC-Switch 切换后重启 Claude Code/Codex；
• 检查是否存在旧的 settings.json 或 config.toml 覆盖配置。

HTTPS 或域名异常

先检查：

curl -I https://api.minoagi.com/health

正常应建立 TLS 并返回成功状态。若浏览器仍显示旧页面，检查代理/VPN的 DNS 缓存。