错误码与限流

错误响应与 OpenAI 格式一致:error.message 给出具体原因,error.type 与 error.code 用于程序判断。4xx 错误(含 402、429、内容安全拦截)不扣费。

错误响应

每个响应(含错误)都带 X-Oneapi-Request-Id 头,网关自身产生的错误多数还会把请求号附在 message 末尾;反馈问题时请提供。流式请求在首字节前出错时同样返回 JSON 错误;已开始输出后出错,错误以 SSE 事件发出。

错误响应示例
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-Oneapi-Request-Id: 20260910110743325678000tMNbU2xW

{
  "error": {
    "message": "Rate limit exceeded (rpm). Please retry after 12 seconds.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded"
  }
}

上游返回的错误原样透传状态码与 message,error.type 为 one_hub_error 的是网关自身产生的错误。Claude 入口的错误以 Anthropic 的形状返回,状态码含义相同。

状态码

状态码含义
400请求体不合法(缺少 model / messages、参数类型错误);models 里有不存在的模型名(invalid_models);命中内容安全词表(content_filter)。
401Key 缺失、无效、已禁用、已过期,或这把 Key 的额度上限已用尽。
402余额不足:个人 Key 为 insufficient_user_quota;组织 Key 为 insufficient_org_quota(组织钱包不足)或 org_monthly_limit_reached(已达到本月花费上限)。
403来源 IP 不在 Key 的白名单内;所属组织已停用;用户组不允许调用 API。
404路径不存在,或费用查询的 id 找不到(generation_not_found)。
413请求体超过上限(默认 16 MB),request_too_large。图片、音频请用 URL 或压缩后再传。
429超出速率限制,rate_limit_exceeded。用户 / 组织级规则触发时带 Retry-After 头(1–60 秒)。上游持续过载、重试超时也返回 429。
503该模型当前没有可用渠道(含模型名写错、模型对你的用户组不可见、Key 的模型限制不允许),或全部渠道重试后仍失败。
5xx上游错误。网关会在首字节前自动换渠道重试,全部失败才把错误返回给你。

速率限制

限制分三层,任一超限即返回 429:

层级说明
用户组每个用户按用户组有默认的每分钟请求数(RPM),所有模型合计。
用户 / 组织级运营可对某个用户或组织、某个模型(或全部模型)单独设 RPM 与 TPM。TPM 按最近 60 秒内已结算的 token 总数计,所以刚超限时会有一分钟左右的冷却。组织 Key 同时受组织规则与你个人规则约束。
上游上游限流或过载时网关会换渠道重试;重试超时仍失败返回 429。

用户 / 组织级规则触发时带 Retry-After 头,按它退避后重试;没有这个头的 429 是用户组默认限制或上游过载,指数退避(1s、2s、4s…)即可。当前对你生效的 RPM / TPM 在用量页底部可见,也可用 GET /api/rate_limit/self 取回;被限流的次数在用量汇总里单独统计。Key 本身没有独立的速率限制。

内容安全

对话与 Claude 接口的输入会经过关键词过滤(词表由运营维护,可整体开关)。命中时请求不会发往上游,返回 400 content_filter,不扣费;被拦截的次数在用量汇总里单独统计。上游自己的安全策略触发时,按上游的返回透传(通常是 finish_reason: "content_filter" 或 4xx 错误)。