New API 手册 / 错误码与限流

错误码与限流

网关错误分两类：网关自身（鉴权/额度/渠道）与上游透传（模型供应商原始错误）。

常见错误

HTTP错误/提示含义处理
400invalid request请求体格式/参数错误检查 JSON 与字段
401invalid token / unauthorized令牌缺失、错误或被删核对 Authorization 与令牌
403无权限 / forbidden令牌无该模型权限或分组受限检查令牌可用模型与分组
404model not found模型不存在或未对你的分组开放查 /v1/models，联系管理员
429rate limited / too many requests触发频率/并发限制退避重试，降低速率
402/其它insufficient quota额度用尽充值或换令牌
500/502/503upstream error上游渠道异常稍后重试；持续则联系管理员
504timeout上游超时重试或换模型/渠道

限流机制

  • 网关可能对单个令牌或用户做请求频率与并发限制；超限返回 429。
  • 部分上游自身也有限流，网关会把其上错误透传。
  • 建议实现指数退避 + 抖动，并尊重 Retry-After 头。
def backoff(i): return min(2 ** i, 30) * 0.5   # 带随机更佳

"transport failure" 类错误

客户端看到 transport failure ... HTTP 403 之类，通常是：Base URL 写错、被防火墙/CORS 拦截、或（对 DSH 等自建前端）请求域名未被信任。确认 base_url 正确、从服务端发起请求、并检查网络出口。

排障三步

  1. 用 curl 最小化复现（只留 model 和一句 messages），排除代码问题。
  2. 看返回体的 error.message 与 x-oneapi-request-id。
  3. 带 request id 联系管理员定位是网关还是上游问题。