OneMux/文档中心/常见问题

常见问题

API 调用遇到报错？按状态码快速定位问题。本页列出最常见的错误码及解决方法，多数问题 1 分钟内可自行解决。

快速排查

代码报错时，先找到 HTTP 状态码（如 401、429），再对照处理：

状态码原因解决方法
401API Key 无效检查密钥格式（sk-xxx）和有效性
402余额不足控制台充值
404模型 ID 错误从模型页面复制正确的 ID
429请求过快降低频率，10秒后重试
500上游故障稍后重试或切换模型

401 - API Key 无效

最常见原因：

  • 复制时多了空格
  • 格式不对（不是 sk- 开头）
  • 密钥已删除

快速解决：

# ✅ 正确格式
api_key = "sk-1234567890abcdef"

# ❌ 常见错误
api_key = " sk-1234567890abcdef "  # 前后有空格
api_key = "1234567890abcdef"       # 缺少 sk- 前缀

前往控制台重新复制或创建新密钥。

402 - 余额不足

账户余额不够支付本次请求。

前往费用中心充值即可。

注意： 长上下文请求（如 Gemini 处理 100 万 tokens）会预扣最大可能费用，确保余额充足。

404 - 模型不存在

常见原因：

  • 模型 ID 拼写错误
  • 使用了旧模型名称（如 gpt-4o 已被 gpt-6.1-sol 替代）
  • Base URL 路径错误

解决方法：

获取正确的模型 ID

  1. 1

    访问模型页面

    打开 https://onemux.net/models

  2. 2

    找到需要的模型

    搜索或浏览找到目标模型

  3. 3

    复制模型 ID

    点击复制按钮或手动复制完整 ID

确认 Base URL 为 https://api.onemux.net/v1（注意末尾有 /v1）

429 - 请求过快

短时间内发送过多请求，触发频率限制。

解决方法：

  • 降低请求频率
  • 等待 10-30 秒后重试
  • 添加自动重试逻辑（见错误处理文档）
  • 减少并发任务数量

500/502/503 - 服务故障

上游模型服务暂时不可用。

解决方法：

  • 等待 10-30 秒后重试
  • 切换到其他模型
  • 检查状态页面了解服务状态

不确定问题时的排查顺序

逐步排查

  1. 1

    检查余额

    登录控制台确认余额充足

  2. 2

    检查 API Key

    重新复制完整密钥，确保无空格

  3. 3

    检查模型 ID

    从模型页面重新复制

  4. 4

    检查 Base URL

    确认为 https://api.onemux.net/v1

  5. 5

    重启软件

    保存配置后重启客户端