错误码与限流
错误响应与 OpenAI 格式一致:error.message 给出具体原因,error.type 与 error.code 用于程序判断。4xx 错误(含 402、429、内容安全拦截)不扣费。
错误响应
每个响应(含错误)都带 X-Oneapi-Request-Id 头,网关自身产生的错误多数还会把请求号附在 message 末尾;反馈问题时请提供。流式请求在首字节前出错时同样返回 JSON 错误;已开始输出后出错,错误以 SSE 事件发出。
错误响应示例
上游返回的错误原样透传状态码与 message,error.type 为 one_hub_error 的是网关自身产生的错误。Claude 入口的错误以 Anthropic 的形状返回,状态码含义相同。
状态码
| 状态码 | 含义 |
|---|---|
400 | 请求体不合法(缺少 model / messages、参数类型错误);models 里有不存在的模型名(invalid_models);命中内容安全词表(content_filter)。 |
401 | Key 缺失、无效、已禁用、已过期,或这把 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 错误)。