常见问题排查

余额不足

Q1: 提示 "Insufficient Balance" 或 "Quota Exceeded" (余额不足)

表现： 接口返回 402 Payment Required 或 429 Too Many Requests，提示余额不足。

• 原因分析：
  1. 上游欠费： 企业绑定的模型渠道（如阿里云百炼、DeepSeek 官方账号）余额已耗尽。
  2. 网关限流： 如果 Cherry Studio 配置了速率限制（Rate Limit），可能触发了短时风控。
• 解决方案：
  • 请管理员前往 模型管理 检查对应渠道的 API Key 是否有效。
  • 登录上游模型提供商（Provider）后台（如阿里云百炼控制台）检查账户余额。
  • 临时救急： 在 分组管理 中，将该用户所属分组的默认模型切换至其他有余额的渠道。

找不到模型

Q2: 提示 "Model Not Found" (找不到模型)

表现： 接口返回 404 Not Found，报错信息包含 The model 'xxx' does not exist。

• 原因分析：
  • 用户在 API 请求体（Body）中请求的模型名称（如 qwen-plus），并不在该用户所属 分组 的可用模型列表中。
• 解决方案：
  1. 检查请求体： 确认用户代码中 model 参数的值。
  2. 检查分组权限： 进入 分组管理 > 选择该用户所在分组 > 检查 模型路由 配置，确认是否已勾选该模型。
  3. 别名映射： 确认是否在系统后台对模型名称做了重映射（例如将 qwen-max 内部映射为 qwen3-max）。

鉴权失败

Q3: 提示 "401 Unauthorized" (鉴权失败)

表现： 接口直接拒绝连接。

• 原因分析：
  • Key 输入错误（多了空格）。
  • Key 已被人为禁用或已过期。
• 解决方案：
  • 在 密钥设置 面板中，检查 启用状态 开关是否开启。
  • 检查 过期时间 是否早于当前时间。
  • 若确认无误，建议删除旧 Key，重新生成一个新的 sk- 密钥。

无可用上游

Q4: 提示 "No Healthy Upstream" (无可用上游)

表现： 接口返回 502 Bad Gateway 或 503 Service Unavailable。

• 原因分析：
  • 该用户所在分组配置的所有模型渠道均已离线（或连接超时）。
• 解决方案：
  • 前往 模型管理，点击 Check 按钮测试模型渠道的连通性。
  • 检查服务器的网络环境是否能正常访问对应服务商的 API（如 dashscope.aliyuncs.com）。