错误码

ModeXFlow 遵循 OpenAI 错误响应格式：

{
  "error": {
    "message": "详细描述",
    "type": "错误类别",
    "code": "机器可读代码",
    "param": "涉及的参数（可选）"
  }
}

同时响应头会带 x-oneapi-request-id，排错必须贴这条 ID 给管理员。

常见错误速查

4xx（客户端错）

状态	code	含义	处理
401	unauthorized	Key 拼错、被禁用、被删除	检查 Key，或去控制台看是否被禁
401	invalid_api_key	Key 格式不对	Key 前面要带 sk-
401	token_expired	Key 过期	建新 Key 或改过期时间
402	insufficient_user_quota	账户余额不足	充值
402	insufficient_token_quota	令牌级额度不足	提高该 Key 的额度或换 Key
403	model_not_allowed_by_token	Key 的模型白名单没这个模型	编辑 Key，加白名单
403	ip_not_allowed	IP 不在 Key 的白名单里	加白名单或换 Key
404	channel_not_found / 无可用渠道	你 Key 的分组下没这个模型	换分组或换模型
404	model_not_found	模型名拼错	见 模型列表
429	rate_limit_exceeded	触发速率限制	加指数退避 (backoff) 重试

5xx（服务端错）

状态	code	含义	处理
500	internal_error	网关内部错	贴 request_id 找管理员
502	upstream_error	上游供应商挂了	稍后重试，网关会自动切下一条渠道
503	service_unavailable	网关/上游都不可用	状态页看下整体状况
504	upstream_timeout	上游响应超过 30 分钟	减小 max_tokens；或分批请求

逐条说明

401 Unauthorized

最常见的失败。检查顺序：

1. Header 拼写：Authorization: Bearer sk-xxx（Bearer 大小写有些实现敏感，标准是 Bearer）
2. Key 是否带了 sk- 前缀
3. Key 是否已被禁用（控制台看）
4. Key 是否已过期（有些 Key 设了过期时间）
5. 换行/空格——粘 Key 时容易带上尾部换行，用 echo -n $KEY | wc -c 验证长度

402 Insufficient Quota

有两层：账户级和令牌级。

• 账户级（insufficient_user_quota）→ 充钱
• 令牌级（insufficient_token_quota）→ 这把 Key 单独有个上限，编辑 Key 调高（或勾选「无限额度」）

生产系统建议监控 remaining_quota 字段（响应头 x-remaining-quota，如有），提前预警。

403 IP Not Allowed

Key 设了 IP 白名单但请求来源不在里面。

• 检查客户端出口 IP是不是白名单里那些（在 curl 命令行执行 curl ifconfig.me 看）
• 云函数/CI 的出口 IP 可能是大段动态的，要加 CIDR 而不是单 IP
• 完全没配白名单的 Key 不受这个错误影响

404 无可用渠道 / channel_not_found

这个最容易踩，它其实是路由失败：

你的 token → 分组 X → 想调模型 Y → 但分组 X 下没有支持模型 Y 的渠道 → 404

修复：

• 换成分组里支持的模型（矩阵）
• 或者把 Key 换到支持这个模型的分组

429 Rate Limit

触发速率限制。响应会带 retry-after 头（秒数）。

推荐的指数退避：

import time, random
for attempt in range(5):
    r = requests.post(...)
    if r.status_code != 429:
        break
    wait = int(r.headers.get("retry-after", 2**attempt + random.random()))
    time.sleep(wait)

排错通用步骤

1. 拿到响应头里的 x-oneapi-request-id
2. 记下你 Key 的名字（不是完整 Key）
3. 描述你请求的 model、时间点、大概是啥业务
4. 发给管理员，能秒定位

对生产系统建议日志里都留 request_id，方便事后关联。