刚上手 AI,最容易被一堆英文报错卡住:不知道是 Key 错了、额度没了,还是自己参数写错了,越查越乱。这篇不讲底层原理,只给一套能照着走的排查顺序:先分清报错属于哪一类,再逐层往下缩,最后判断什么时候该停下来换方案。
刚上手 AI,最容易被一堆英文报错卡住:不知道是 Key 错了、额度没了,还是自己参数写错了,越查越乱。这篇不讲底层原理,只给一套能照着走的排查顺序:先分清报错属于哪一类,再逐层往下缩,最后判断什么时候该停下来换方案。
先记住一个原则:报错不是用来「猜」的,是用来「分」的。同一条报错,落在身份、额度、请求、环境四个筐里,你要打开的文件和要改的地方完全不同。下面按从外到内的顺序讲,每节都给你判断标准和具体动作。
第一步不是改代码,是给报错分类
看到报错的第一反应别是打开编辑器,而是问自己:这条错在说「你是谁」「你还有没有钱」「你问得对不对」「你连不连得上」。四类分清楚,你才知道该去看哪一页文档,而不是在代码里乱试一通。
- 身份类
- Key 无效、权限不足、账号被限制,关键词常见 invalid、unauthorized、forbidden
- 额度类
- 余额不足、免费额度用完、触发限速,关键词常见 quota、balance、rate limit
- 请求类
- 参数缺失、格式错误、内容太长,关键词常见 missing、invalid request、too long
- 环境类
- 连不上、超时、地址不对,关键词常见 timeout、connection、not found
看报错时优先抓状态码和英文关键词,比通读整段文本快得多:数字码定大类,关键词定细节。具体某个码大致指向什么,去 /ai-dict 对照,别凭记忆。还有个高频坑:嵌套报错里真正抛出的那条往往不在最后一行,往上翻两三行再下结论。
身份和额度:最容易被误判成「代码写错了」
新手最容易把身份和额度问题当成代码问题,反复改请求体却毫无进展。这两类错的共同点是:代码本身没错,错在账户侧或配置侧,所以验证方式也不该是读代码。
- Key 是否复制完整,前后有没有多余空格或换行,是不是把别家平台的 Key 串用了
- 环境变量到底有没有被运行环境读到:在代码里打印一下读到的值长度,比盯着配置文件靠谱
- 账户侧状态去对应平台控制台看当时的数字:余额、免费额度、是否触发限速,别凭印象判断
- 换过 Base URL 或中转地址的,优先怀疑地址和模型名,而不是 Key 本身
这里有个判断标准:如果你只是改了代码逻辑、Key 和账户都没动,报错却从「参数错误」变成「身份错误」,那多半是配置被覆盖或环境变量加载顺序出了问题,回头查配置,不要继续调参数。
请求层:参数、格式和长度三个高发点
排除了身份和额度,就进入请求层。这类错最好查,因为报错通常说得比较具体,坏处是新手容易一次改好几处,改完不知道是哪处生效。原则是:一次只改一处,改完立刻用最小请求验证。
- 核对模型名确认这个模型名在该平台确实存在,拼写、大小写、前缀都对齐平台文档,不要照抄别家的写法。
- 校验请求体确认是合法 JSON,必填字段齐全,引号、逗号、括号没有漏;可以用一个 JSON 校验工具先过一遍。
- 缩小到最小请求一条短消息、不带任何额外参数先跑通;能通说明是参数问题,不通再回到环境层查。
- 估算输入规模上下文超限常被误读成「服务挂了」,先估算这次输入的 token 量,再对照模型上限;估算口径可到 /tools/token-price-calculator 看。
判断标准很简单:最小请求能跑通、加回参数就报错,问题一定在你加回去的那部分。这时候别重装环境、别换 Key,逐个参数加回去做二分,比对着文档逐字比对快。
环境层:本地能跑、线上报错怎么查
环境类报错最像「玄学」,因为代码一个字没改,换个地方就跑不通。其实它有明确的判断标准:同一个最小请求,在别的网络能通、在你这里不通,基本就是环境问题,继续改代码没有意义。
| 现象 | 大概率原因 | 先做什么 |
|---|---|---|
| 本地通、线上超时 | 出口网络或代理拦截 | 量一遍到目标接口的延迟基线 |
| 所有请求都连不上 | Base URL 写错或服务不可达 | 核对地址与文档是否一致 |
| 偶发超时、重试就好 | 线路抖动或限速 | 记录发生频率,别急着改代码 |
| 换网络就正常 | 公司网、校园网或代理策略 | 换网络复现确认,再找网管 |
具体动作上,先用 /tools/speed-test 量一遍到目标接口的延迟基线,再确认 Base URL 结尾斜杠、版本路径是否和文档一致。这两处是新手最高频的「玄学报错」来源,改完立刻用最小请求复测。
一套固定的二分排查顺序:从外往里缩
报错一多,人就容易跳步:明明网络不通,却在改参数。给你一个固定顺序,每次只验证一件事,验证通过再往下走,能保证你不原地打转。
- 第一层:网络能不能到用最小请求测连通性,通了再往下;不通就查地址、代理和出口网络。
- 第二层:身份认不认确认 Key 有效且用对平台,环境变量确实读到;不认就查账户和控制台状态。
- 第三层:额度够不够看余额、免费额度和限速状态,去对应平台控制台看当时的数字。
- 第四层:参数对不对模型名、JSON 格式、必填字段、输入长度逐项核对。
- 第五层:内容是否触发限制敏感内容、格式限制类报错按平台规则调整,不要靠反复重试。
每层都要留下可复现的最小样例,别在改动过的代码上反复试,否则分不清是哪次改动生效。卡住时间明显超出预期就换路:换一个已知可用的 Key,或换一个平台发同一个请求,用来反向证明问题在谁那边。
怎么读报错信息:抓关键词而不是抓全文
很多人读报错是从头读到尾,读完更迷茫。正确姿势是先扫状态码,再扫关键词,最后只精读指向问题的那一两句。下面这张对照表可以贴在顺手的地方。
| 关键词 | 指向 | 下一步 |
|---|---|---|
| invalid / unauthorized | 身份或 Key 问题 | 查 Key 与平台匹配 |
| missing / required | 参数缺失 | 核对必填字段 |
| exceeded / too long | 超出上限 | 估算输入规模 |
| limit | 限速或额度 | 看账户侧状态 |
| timeout / connection | 网络或地址 | 测连通性与延迟 |
遇到不认识的英文术语,去 /ai-dict/category/basics 查,比搜索引擎快,也不容易被过时帖子带偏。另外,把报错原文完整保留下来再搜或再问人,截断一半的报错基本没法定位,这是最亏的一种省事。
什么时候该停手:不可控报错和平台侧问题
排查不是死磕。有些报错你改到天亮也没用,因为问题不在你这边。判断标准是看这条错是否可复现、是否只发生在某一家:只在某一家失败,问题多半在那家平台;到处都失败,问题大概率在你的输入或本地环境。
- 服务端错误、平台整体异常、区域限制这类,先看 /ai-status 有没有已知故障,再决定等还是换
- 同一个请求在多个平台都失败,回头查自己的输入和本地环境,别继续换平台
- 只在某一家失败,去那家的文档和公告里找,不要拿别家的经验硬套
- 涉及付费、合规、账号封禁类报错,不要靠自行重试解决,按平台流程走
什么时候该换方案:同类报错反复出现、已确认不属于你的可控范围、且继续排查的收益明显低于换一条路。这时候换平台或换接入方式,比继续在报错里耗着划算。哪家中转站更适合你的场景,可以到 /sites 看当时的资料和检测结果。
一张出门前自查清单
下次再遇到报错,按这张清单从上往下过一遍,大部分问题在前几行就能定位。清单的价值不在全,而在顺序固定,让你不跳步。
- Key 完整、未过期、用对了平台,环境变量在运行环境里确实读到
- Base URL 与文档一致,模型名在该平台存在,请求体是合法 JSON
- 本次输入规模在上下文上限内,账户余额与限速状态已确认
- 最小请求可复现,报错原文已完整保留,知道自己卡在哪一层
- 超出可控范围的,已确认平台侧状态并决定等还是换
最后提醒一句:排查记录比排查结论更值钱。把每次卡住的层级、改了什么、验证结果记下来,下次同类报错能直接跳到答案,这比背一堆报错码有用得多。
报错先分类,排查按层缩;改一处,验一处,留一个能复现的最小样例。下一步想顺手查某个报错码到底指什么、或者对照各家接口的接入说明,去站内词典按关键词搜一遍,比翻聊天记录快。→
常见问题
报错是英文,看不懂怎么办?
不要逐词翻译。先找数字状态码定大类,再找 invalid、missing、exceeded、timeout 这类关键词定细节,然后到站内 AI 术语词典查对应概念,基本能判断是身份、额度还是参数问题。
同样的代码昨天能跑今天报错,是什么原因?
优先怀疑三件事:额度或免费额度用完、平台侧限速或故障、你换了模型名或地址。先用最小请求复测,再去看账户状态和服务监控页,不要第一时间改代码。
改了很多次还是不通,要不要推倒重来?
先确认你有没有留下一个「曾经的最小可复现样例」。没有的话先补一个,再一步步加参数,比整段重写更快找到是哪一步引入的问题。超过合理时间就换已知可用的 Key 反向验证。
不知道是平台的问题还是我的问题,怎么判断?
用同一个请求分别打到两个不同平台:都失败说明输入或本地环境有问题,只有一个失败说明是那家平台侧的事,接着去看它的服务状态和文档公告。
新手最容易忽略的报错原因是什么?
地址和模型名对不上。很多报错看着像 Key 失效或服务异常,实际是 Base URL 版本路径或结尾斜杠写错、模型名在该平台不存在。先把这两项核对一遍再排查别的。