帮助

错误码与排查

调用出错时怎么看懂报错：错误的格式、常见状态码和错误信息的含义、该怎么处理，以及什么时候应该重试。

错误长什么样

出错时，NoviaHub 返回一个 HTTP 状态码（如 401、403、503）和一段 JSON。大多数错误是 OpenAI 的格式：

{
  "error": {
    "message": "Invalid token (request id: 202609281537468941710008268d9d6GzbHDLkB)",
    "type": "new_api_error",
    "param": "",
    "code": ""
  }
}

message：错误说明。末尾括号里的 request id 是这次请求的编号，联系客服时请一并提供。
code：错误码。有的错误没有错误码，这时是空字符串。
type：由 NoviaHub 自己产生的错误，这里大多是 new_api_error，地址不存在时是 invalid_request_error；由上游模型厂商返回的错误，保留厂商原来的值。

用 Anthropic 接口（/v1/messages）调用时，部分错误会以 Anthropic 的格式返回，外层多一个 "type": "error"：

{
  "type": "error",
  "error": {
    "type": "new_api_error",
    "message": "用户额度不足, 剩余额度: ＄0.000000 (request id: ...)"
  }
}

Anthropic 格式里只有 type 和 message，没有 code 字段，要靠 message 判断是哪种错误。

但是像 Key 无效、模型不在 Key 的允许范围内这类在请求刚进来时就被拦下的错误，即使走 /v1/messages，也会以上面的 OpenAI 格式返回。

另外：

错误信息的语言：部分错误信息会翻译成中文或英文，例如 Invalid token 和「无效的令牌」。优先用你账户里保存的界面语言（登录 NoviaHub 网站后切换语言，就会保存到账户），其次看请求头 Accept-Language，都没有时用英文。有中文译文的错误，下表一并列出；只有中文的错误已标出。
请求编号：每个响应都带有 X-Oneapi-Request-Id 响应头，值就是请求编号。

常见错误一览

以下内容来自在本地测试实例（与线上同一版本）中实际触发的结果，并对照了网关源码。

401：身份验证失败

错误信息	原因	怎么办
`Invalid token`（中文：「无效的令牌」）	没带 API Key、Key 写错了，或者这把 Key 已禁用、已过期、已耗尽。这几种情况的报错完全一样。	到「API 密钥」页面检查这把 Key 的状态。确认 Key 完整复制、没有多余的空格或换行。
同上	用错了放 Key 的请求头。例如在 `/v1/chat/completions` 上用了 `x-api-key` 或 `x-goog-api-key`。	改用 `Authorization: Bearer <API Key>`，或按接口地址与协议选择使用对应的请求头。

403：没有权限

错误信息	错误码	原因	怎么办
`This token has no access to model {模型名}`（中文：`该令牌无权访问模型 {模型名}`）	（空）	这把 Key 设置了「模型限制」，而这个模型不在允许列表里	编辑 Key，把模型加进「模型限制」，或清空限制
`您的 IP 不在令牌允许访问的列表中`（只有中文）	`access_denied`	这把 Key 设置了「IP 白名单」，而当前 IP 不在其中	编辑 Key 的 IP 白名单（每行一个 IP），或清空
`用户额度不足, 剩余额度: ＄0.000000`（只有中文）	`insufficient_user_quota`	账户余额已经用完（为 0 或负数）	到钱包充值
`预扣费额度失败, 用户剩余额度: ..., 需要预扣费额度: ...`（只有中文）	`insufficient_user_quota`	余额还有，但少于这次请求的预扣估算，见计费说明	充值；或者减少这次请求的输入内容
`token quota is not enough, token remain quota: ..., need quota: ...`	`pre_consume_token_quota_failed`	这把 Key 设置了额度上限，剩余额度不够这次请求预扣	编辑 Key，调高额度或开启「无限配额」
`普通用户不支持指定渠道`（只有中文）	（空）	Key 末尾多拼了 `-数字` 之类的后缀	使用从「API 密钥」页面复制的原始 Key

400：请求内容有问题

错误信息	错误码	原因	怎么办
`Model name not specified, model name cannot be empty`（中文：`未指定模型名称，模型名称不能为空`）	（空）	请求里没有 `model` 字段	加上模型名
`field messages is required`	`invalid_request`	缺少必填字段	按接口文档补全字段
`Invalid request: ... invalid JSON request body`（中文以 `无效的请求，` 开头）	（空）	请求体不是合法的 JSON	检查引号、逗号、括号是否配对
`模型 {模型名} 的价格尚未由管理员配置...`（中英双语）	`model_price_error`	这个模型还没有开放	换一个在模型&价格上能看到的模型
`unsupported model modifier "..."` / `invalid effort modifier value "..."`	`convert_request_failed`	模型名后面的 `@` 修饰符写错了	按推理与思考的写法修改
`n must be an integer between 1 and 128`	`invalid_request`	图片生成的张数超出范围	`n` 填 1 到 128

404：地址不对

错误信息	原因	怎么办
`Invalid URL (POST /v1/...)`	请求的路径不存在。常见于地址里多写或少写了 `/v1`，或者调用了 NoviaHub 不提供的接口（例如 `/v1/messages/count_tokens`、Gemini 的 `:countTokens`）	对照接口地址与协议选择检查地址

503：模型暂时不可用

错误信息	错误码	原因	怎么办
`No available channel for model {模型名} under group default (distributor)`（中文：`分组 default 下模型 {模型名} 无可用渠道（distributor）`）	`model_not_found`	模型名写错了（大小写、连字符、多了空格），或者这个模型目前没有可用的线路	从模型&价格复制准确的模型 ID。确认无误仍然出错，请稍后再试或联系客服

其他

现象	原因	怎么办
HTTP 500，`get file data failed: ...` 或 `get file data from '...' failed: ...`，错误码 `convert_request_failed`	消息里的图片链接无法下载	改用 base64 图片，或换一个公网可访问的链接，见图片输入
HTTP 500，`not supported model for image generation, only imagen models are supported`	用 `/v1/images/generations` 调用了 Gemini 图片模型	改用 Gemini 接口或 Chat 接口，见图片生成
HTTP 429 或 5xx，错误信息来自模型厂商	上游模型厂商限流或出错。NoviaHub 会把厂商的状态码和错误信息原样转给你；厂商给了 `Retry-After` 响应头的，也会一并转发。	稍后重试，见下方重试建议
HTTP 200，但返回的是一整个网页（HTML），程序报「无法解析 JSON」	OpenAI 协议的地址漏写了 `/v1`，请求落到了网站页面上	把 base URL 改成 `https://noviahub.com/v1`
返回的是 HTML 错误页（不是 JSON），状态码可能是 403、502、524 等	请求在到达 NoviaHub 之前，就被网站前面的网络防护或代理层拦下了，或者超时了	记下发生时间、请求的地址和状态码，联系客服

什么时候应该重试

可以重试：429（限流）和 5xx（服务端或上游错误）。建议等待一段时间再重试，每次失败后把等待时间加倍（例如 1 秒、2 秒、4 秒……），并设置最多重试几次。响应里有 Retry-After 时，至少等待它给出的秒数。
不要重试：400、401、403、404。这些是请求本身或账户设置的问题，原样重试只会得到同样的错误，应先按上表修正。

失败的请求不收费：预扣的金额会退回，详见计费说明。

联系客服

发邮件到 support@noviahub.com，请附上：

错误信息里的 request id，或响应头 X-Oneapi-Request-Id 的值；
发生时间（精确到分钟，并注明时区）；
调用的地址、模型名，以及完整的报错内容。

不要在邮件里发送你的 API Key。