OpenBridger实用教程
EN 进入控制台

错误码

网关自己拒绝请求时,正文是这种形状:

{
  "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 或密钥泄露 不要在网页里放密钥。由你自己的服务器调用。

相关

输入关键词开始搜索