错误码
网关自己拒绝请求时,正文是这种形状:
{
"error": {
"message": "说明文字 (request id: 请求ID)",
"type": "new_api_error",
"code": "错误码,可能是空字符串"
}
}
响应头 X-Oneapi-Request-Id 与正文里的 request id 是同一个值。发给支持人员时带上它,不要带完整 API Key。
上游返回的错误可能保持上游的 type 和 HTTP 状态,不一定是 new_api_error。下表只覆盖网关自己发出的、调用方最常遇到的情况。
认证和权限
| HTTP | code | 你看到的意思 | 怎么处理 |
|---|---|---|---|
| 401 | 空 | 「无效的令牌」 | 密钥错误、已禁用、已过期,或这把密钥的剩余额度用尽。钱包有余额也一样。重新复制 sk- 开头的密钥,或提高该密钥额度。 |
| 401 | 空 | 「未提供令牌」 | 没有 Authorization 头。应是 Bearer 加密钥。 |
| 403 | 空 | 「无权访问某分组」或「分组某已被弃用」 | 密钥上的分组不在你的可用范围内。改回账户分组或 auto。 |
| 403 | access_denied |
IP 不在令牌允许列表,或无法解析客户端 IP | 改密钥的 IP 白名单,或去掉白名单后再试。 |
| 403 | 空 | 账号被封禁 | 用注册邮箱联系支持,不要继续撞同一密钥。 |
| 403 | 空 | 「普通用户不支持指定渠道」 | 密钥里不要附加 -渠道ID。 |
Anthropic 客户端把密钥放在 x-api-key 时,只在 /v1/messages 和 /v1/models 上会被接受。其他路径请用 Authorization: Bearer。
额度和计费
| HTTP | code | 文案要点 | 怎么处理 |
|---|---|---|---|
| 403 | insufficient_user_quota |
「用户额度不足」或「预扣费额度失败」 | 钱包不够这次预扣。充值、兑换,或换更短的输入。 |
| 403 | insufficient_user_quota |
「订阅额度不足或未配置订阅」 | 当前偏好是「仅用订阅」或订阅余额不够。改成「优先钱包」或给钱包充值。见 订阅套餐。 |
额度不足是 403,不是 429。
模型和请求
| HTTP | code | 文案要点 | 怎么处理 |
|---|---|---|---|
| 400 | 空或请求类错误 | 模型名为空、正文无法解析 | 检查 JSON 和 model 字段。 |
| 503 | model_not_found |
「分组 … 下模型 … 无可用渠道」 | 从模型广场重新复制 ID,并确认密钥分组。这不是「地址打错了」的 404。 |
| 501 | api_not_implemented |
API not implemented |
该路径未实现。图像变体、文件、微调属于这类。 |
| 429 | 空 | 「您已达到请求数限制」或「总请求数限制」 | 应用级频率限制打开时才会出现,窗口和次数写在文案里。降低并发,等窗口过去。 |
| 500 | 空 | 数据库错误一类的内部失败 | 记下 request id 再联系支持。不要立刻用同一把密钥无限重试。 |
上游限流时,状态码可能是上游的 429,正文也是上游的。那种 429 和上面的本地频率限制不是同一条规则。稍后重试,或换一个广场里可用的模型。
客户端侧看起来像网关错误、其实不是
| 现象 | 实际原因 |
|---|---|
地址变成 /v1/v1/chat/completions |
Base URL 已经含 /v1,客户端又加了一次。OpenAI 兼容客户端填 https://openbridger.com/v1。 |
| Claude Code 打到错误主机 | ANTHROPIC_BASE_URL 应是 https://openbridger.com,不要带 /v1。客户端会自己请求 /v1/messages。 |
模型列表是空的,但 curl /v1/models 有数据 |
客户端过滤了不认识的 ID。手工填写模型广场里的完整 ID。 |
| 浏览器直接调用报 CORS 或密钥泄露 | 不要在网页里放密钥。由你自己的服务器调用。 |