NewAPI 常见报错与排查顺序：从额度到渠道逐层定位

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

NewAPI 出问题时，别一上来就重启容器。翻一遍官方 FAQ 会发现一个共同特点：绝大多数报错的根因是「某一处配置没对上」，而不是程序本身坏了。账户里明明有额度却提示额度不足，官方给的解释是令牌额度和账户额度本来就是分开的两个量；提示「无可用渠道」，官方让你查的是用户分组、渠道分组、渠道模型这三处设置；渠道测试报 invalid character '<' looking for beginning of value，说明上游返回的压根不是 JSON 而是一张 HTML 页面。所以有效的排查顺序是分层的：先确认网关进程本身活着，再判断这条报错出在额度层、渠道层还是客户端层，最后才去动数据库和环境变量。下面按这个顺序把官方文档里写明的报错和对应检查项串起来。

第零步：先确认网关自身是活的

官方给出的 Docker Compose 配置里，new-api 服务带了一条健康检查，做法是请求 /api/status 这个接口，再在返回体里匹配 "success" 是否为 true，匹配不到就判定为不健康。这条健康检查探的是进程与 HTTP 服务本身是否可用，官方没有说明它与额度、渠道、倍率这些业务配置之间是什么关系。但有一点是成立的：如果连它都不通，那后面所有关于分组和倍率的排查都是白费力气，先把服务本身弄活。

「更新之后服务起不来」是官方单独列出的一类问题，文档给的三个检查方向依次是：看日志里的错误信息、确认数据库连接是否正常、确认环境变量配置是否正确。顺序本身就有信息量——先看日志再看依赖，最后才怀疑配置。与之并列的还有两类：更新后功能异常（检查 API 格式是否有变化、前后端版本是否匹配、新版本是否需要额外配置），以及数据库结构不兼容（查更新日志里的迁移说明、确认是否需要手动执行迁移脚本）。

如果你是用 1Panel 部署且界面打不开，官方那一节给的检查项更偏基础设施：确认应用状态是「已启动」、确认端口正确映射并放行、检查服务器防火墙与云服务器安全组。

额度类报错：账户里明明还有额度

官方 FAQ 有一条专门回答「账户额度充足为什么还提示额度不足」。答案是令牌额度与账户额度是分开记的：令牌额度只用来设置这把令牌的最大使用上限，用户可以自由设定，官方让你先去检查令牌额度是否充足。

注意官方描述的是这一种情形——账户够而令牌不够时会拦下请求。所以看到「额度不足」，第一反应不该是去钱包充值，而是打开令牌列表看那一栏的上限值。这个设计的实际用处是给每把令牌套一个独立的花费天花板，代价就是排查时多了一处容易被忽略的地方。令牌本身的额度、分组、权限怎么设，可以看令牌管理这一篇。

另一条高频提示是渠道测试时报「倍率或价格未配置，请联系管理员设置」。官方给的原文检查路径是「System Settings - Operation Settings - Model Ratio Settings」（系统设置 → 运营设置 → 模型倍率设置），另一条路是在系统设置的运营设置里开启自用模式（Self-use Mode）。

文档在计费那一节把这个行为讲得更完整：对于没有设置倍率的模型，自用模式下系统会套用一个默认倍率（具体数值以官方文档当前版本为准），商用模式下则直接抛出「倍率或价格未配置」的错误，同时管理界面会把这些未配置的模型自动检测并列出来。也就是说，这条报错本质上是模式选择问题——你这台网关是自己用，还是要对外给别人用。倍率相乘的完整规则见分组倍率的计费机制。

渠道类报错：请求根本没走出去

提示「无可用渠道」

官方 FAQ 给的检查清单是三项，顺序不要打乱：用户分组设置、渠道分组设置、渠道模型设置。这三项是一条链——用户属于某个分组，渠道声明自己服务哪些分组，渠道还要声明自己支持哪些模型。链上任何一环没对上，这次请求就找不到能接的渠道。官方另外说明，令牌的分组设为 auto 时，系统会按优先级自动挑一个可用分组，这是为跨分组故障转移准备的。

如果有多条渠道却总走同一条，先看优先级和权重的定义：官方写明优先级数值越大越优先，高优先级的渠道会被先用；权重只在同优先级的渠道之间起作用，按比例分配请求。这两个参数的语义经常被记反。

渠道测试报 invalid character '<' looking for beginning of value

官方解释这个错误的含义是返回值不是合法 JSON 而是一张 HTML 页面，最可能的原因是部署站点的 IP 或代理节点被 CloudFlare 拦下了。这条值得记住的原因是它的表象极具迷惑性——看上去像是 JSON 解析 bug，实际是网络出口层的问题，改多少遍渠道配置都没用。

提示「当前分组负载已饱和，请稍后再试」

官方对这句提示的解释只有一句：说明上游渠道遇到了 429（Too Many Requests）。也就是说这是上游在限流，不是你的网关在限流。网关侧能做的是让请求有别的去处：多 Key 模式允许一条渠道挂多把 API Key 自动轮询，失败的 Key 会被自动跳过、恢复后重新启用，轮询方式官方给了顺序轮询和按权重随机两种。客户端侧该怎么退避重试，可以参考429 的通用处理思路。

客户端连不上：错误往往在客户端那一侧

官方为 ChatGPT Next Web 报 Failed to fetch 给了三条检查项：部署时不要设置 BASE_URL；确认 API 地址和 API Key 填写正确；检查是否启用了 HTTPS——在 HTTPS 域名下，浏览器会拦截发往 HTTP 的请求。最后这条是纯浏览器行为，跟 NewAPI 无关，但它造成的现象和网关挂了一模一样。

模型名对不上是另一类常见原因。官方在 AQBot 的接入 FAQ 里写：导入成功但对话失败时，点「同步模型」，并确认模型 ID 与 NewAPI 实际暴露出来的名字一致。在 OpenClaw 那一节，官方把「baseUrl 缺少 /v1」直接称为最常见的接入错误之一，同时提到模型 ID 必须与配置里声明的 id 对应。这两条都是特定客户端章节里的说法，别直接套到别的客户端上——不同客户端对地址是否自动补全 /v1 的处理并不一样，官方在 AQBot 那一节就专门写了它会自动补全的规则。

空回复与超时：两个环境变量的反向陷阱

官方 Docker Compose 示例里有一行被注释掉的 STREAMING_TIMEOUT，注释写的是「如果遇到空补全（empty completions）就调大它」。这是一条很难自己想到的线索：流式请求返回空内容，第一嫌疑人是单次流式响应的超时时间，而不是模型或提示词。

RELAY_TIMEOUT 则相反，官方为它挂了一条警告，说设得过短会导致上游 API 已经完成请求并完成计费，而本地因为超时导致计费失败，进而造成计费不同步、系统产生损失，并明确建议「除非你清楚自己在做什么，否则不要设置它」。把中转超时调小看上去是保护自己，实际是在给自己制造对不上账的账单。

数据库与升级：动手之前先读这几条

官方 FAQ 里有一条报错是手动改过数据库之后出现的「数据一致性已被破坏，请联系管理员」。解释是系统在 ability 表里检测到了无效的渠道 ID 记录，常见原因有两个：删除 channel 表记录时没有同步清理 ability 表里的无效渠道；以及渠道支持的每个模型都需要在 ability 表里有对应记录。换句话说，这两张表是要配对维护的，直接用 SQL 改库很容易破坏这层对应关系。

升级会不会丢数据，官方按数据库类型分了两种情况：MySQL 不会丢；SQLite 需要按部署命令挂载数据卷来持久化数据库文件，否则容器重启后数据会丢失。至于升级前要不要先改数据库结构，官方说一般不需要，系统会在初始化时自动调整；确实需要特殊处理时会在更新日志里说明并提供相应脚本。所以升级前真正该做的动作是读更新日志，而不是先动手改表。

官方还给了一份升级后的检查清单，五项：能否正常登录并访问管理界面、系统日志里有没有错误或警告、抽几个 API 调用测一下、数据库结构更新是否成功、所有渠道连接是否正常。

多节点部署有一组独有的故障。登录后会话失效，官方在面板部署那一节给的答案是确保 SESSION_SECRET 已设置且不为空；环境变量文档里还有一条更硬的约束——这个值不能直接填 random_string 这个占位串，否则程序会拒绝启动。集群排障那一节列了三类现象：节点无法同步数据（核对每个节点的 SQL_DSN 是否指向同一个数据库、SESSION_SECRET 是否完全一致、共享 Redis 时 CRYPTO_SECRET 是否匹配）、负载不均衡（检查负载均衡器配置与权重）、会话丢失（所有节点用同一个 SESSION_SECRET 和共享数据库）。其中有一条特别容易被误判成故障：使用独立 Redis 时，版本轮换之后出现短暂 401 属于预期内，应该在 SYNC_FREQUENCY 对应的收敛窗口内自行恢复；只有持续失败才需要去查数据库连通性。

让排查有据可依：先把该开的开关打开

上面这些排查动作都建立在「你能看到错误」的前提上。官方提供了几个相关开关：ERROR_LOG_ENABLED 控制是否记录错误日志并在前端展示（默认值以官方文档当前版本为准，官方的 Compose 示例里是显式打开的）；调试类还有 DEBUG（会带上 GORM 的调试输出）、GIN_MODE 和 ENABLE_PPROF。

渠道侧则可以让系统替你先发现问题。渠道列表里每条渠道都能单独点「测试」，弹窗会显示响应时间和成功/失败状态，列表顶部还有一键批量测试所有渠道。渠道高级配置里有「自动禁用」，开启后连续失败会自动禁用该渠道；模型设置里还有一组更细的开关——自动禁用失败模型、触发禁用的失败阈值、以及禁用后的自动恢复时间。这套机制的意义是把「用户报错了我才知道」变成「系统先把坏渠道摘掉」。

日志本身是最后一道定位手段。用量日志里能看到每次调用用的令牌分组、模型和消耗，管理员视图比普通用户多出用户名和渠道名两列，筛选条件支持时间范围、用户名、模型、渠道、令牌名。怎么用这些字段把一次失败定位到具体环节，见日志排查那一篇。

最后：官方希望你在提 issue 之前做三件事

文档的反馈章节写得很直白：提交新 issue 前先搜索是否已有类似 issue、确认自己用的是最新版本、再查一遍 FAQ 文档。这三条其实也是一份排查顺序的浓缩版——先确认不是已知问题，再确认不是旧版本的问题，最后才怀疑是新 bug。

需要提醒的是，本文所有报错含义与检查项都来自官方文档与官方 FAQ 的书面说明。官方 FAQ 覆盖的范围是有限的：额度、渠道配置、部署连接、数据库与升级这四类，超出这四类的报错，官方文档里没有给出对应条目，遇到时更稳妥的做法是按日志逐层定位，而不是照着别处的经验硬套。