API 报错 401/404/502 是谁的问题？实测对照

先把结论放前面：401、404、502 这几个数字本身没多少信息量，有用的是返回体里那行 message。我们把每类报错都在 LONG AI 网关上真跑了一遍，光 404 就有三种完全不同的原因，其中一种还是你自己账号设置造成的。只盯状态码猜，多半会猜错方向、改错地方。

下面的返回原话都是 2026-11-03 当场跑出来的，没有润色。

一、报错要分三段看，不是按数字分

一个请求要过三道关，报错落在哪一段，决定了该谁去改。很多人一看到 404 就去翻模型名，其实可能压根是路径写错了。

第一段查钥匙、格式、路径，全在你自己这边。第二段按模型名挑货源，名字写错、门槛设太严、当下没人挂单都卡在这里。第三段已经转发到卖家上游，跟你无关，只能换渠道或等一会儿。

二、三类 404 长得一样，原因完全不同

下图是每类报错真跑一遍的结果。重点看三行 404：路径写错是纯文本的 404 page not found，连 JSON 都没有；模型名拼错是 is not available；广场上有名字但当下没人挂单，是 is currently unavailable: no upstream provider serves it。

这里有个特别好用的判据：看返回体是不是 JSON。纯文本说明请求根本没进业务逻辑，百分之百是路径或方法写错；能返回 JSON 的，说明已经进到网关里，才轮到看 message。

还有一个更反直觉的：参数类型写错，回的不是 400，而是 502。把 max_tokens 写成字符串 "abc"、把 temperature 写成中文、把 top_p 写成 "high"、把 max_tokens 写成布尔值 —— 四种写法我们都试了，四次全是 502 Upstream request failed；同一个模型、同一分钟、参数正常的那一条，立刻 200。所以 502 有相当一部分概率是你自己的参数问题，不是上游挂了。

三、独家实测：同一个请求，换一把 Key 就变 404

这是最值得记住的一条，来自一次真实排查：同一个请求体、同一个模型名，只换 Key，结果一个 200、一个 404。

404 的字面意思是"上游没有这个模型"，但服务端日志把真实原因写得很清楚：

no available OpenAI accounts supporting model: gemini-3.6-flash
(pool=36, filtered: account_model_not_owned=17 model_unavailable=8 over_price_cap=1)

关键是最后那个 over_price_cap=1 —— 超出价格上限。这把 Key 设了"只接受很便宜的那一档货"，而这个模型当前的折扣没达到要求，于是被它自己设的规则筛掉了。系统对"筛完一个不剩"统一报 404，文案就写成了"上游没货"。

所以看到 no upstream provider serves it，第一件事不是去查上游，而是去查你这把 Key 的折扣门槛。

四、广场上有名字，不等于现在能调通

这条是本文最实用的一条，也是最容易踩的坑：模型广场是挂牌清单，不是可调用清单。有人把货撤了，名字还挂在广场上。

判断办法很简单：广场列表每一行都有「市场最低价」「最高折扣」「供货」三列。「供货」写着 0 家、另外两列是「—」的，就是当下没人挂单。

我们按这个特征从广场 190 个模型名里挑出 20 个"没有卖家数、也没有报价"的，随机抽 4 个各调 2 次，8 次全部失败，一次 200 都没有（4 次 503、1 次 404、3 次超时）。同一时刻，挑 2 个"有卖家数、有报价"的模型调用，都是 200。这不是概率问题，是有货没货的区别。

所以别把广场当成"能用"的证明。写进代码之前先看卖家数和报价，跑批之前先手动调一次。这十秒钟能省掉半夜排查"为什么昨天还好今天全 404"。

五、常见报错速查：问题、原因、怎么解决

1. 401 API_KEY_REQUIRED
原因：请求头里没带 Key。
解决：加 Authorization: Bearer sk-xxx，注意是 Bearer 加一个空格，不是冒号。

2. 401 INVALID_API_KEY
原因：Key 不对，多半是复制时多了空格或换行。
解决：重新复制一次，检查首尾有没有空白字符，别用截图识别出来的 Key。

3. 400 Failed to parse request body
原因：请求体不是合法 JSON，常见于单引号、末尾多逗号、中文引号。
解决：过一遍 JSON 校验工具；自己拼字符串的，改用 json 库序列化。

4. 400 model is required
原因：没有 model 字段，或写成了数字。
解决：model 的值必须是字符串，不能是 123 这种。

5. 404 page not found
原因：路径写错，请求根本没进业务逻辑。
解决：确认是 /v1/chat/completions，少一个 s 就是这行报错。

6. 404 is not available
原因：模型名确实不存在或拼错，网关不认识这个名字。
解决：去模型广场复制准确的名字。

7. 404 no upstream provider serves it
原因：名字认识，但当下没有可用货源；或你的 Key 折扣门槛把它筛掉了。
解决：先看广场上这个模型有没有卖家数，再检查 Key 的折扣门槛。

8. 429 rate_limit_error
原因：上游所有渠道都在限流，不是你的账号被封。
解决：等几秒按指数退避重试，不用改配置。

9. 502 Upstream request failed
原因：先怀疑自己，实测参数类型写错就是这个码。
解决：把参数逐个改成正确类型再试；参数没问题还报 502，才是上游的事。

10. 503 Service temporarily unavailable
原因：这个模型当前一个可用货源都没有，但配置是对的。
解决：过一会儿重试，或换一个同族模型。

六、三步定位法，比背状态码管用

• 第一步，看是不是 401。是就只看 Key，其他信息全是噪音。
• 第二步，看返回体是不是 JSON。纯文本 404 page not found 说明连路由都没匹配上，直接查路径；有 JSON 的才往下看 message。
• 第三步，按 message 里的关键词对号入座。parse / required 是请求体问题；is not available 是名字不认；no upstream 是货源或门槛问题；rate-limited 是上游限流；Upstream request failed 先查自己的参数类型。

核心就一句：先分清责任在谁，再决定改哪里。把上游的问题当成自己的问题去改配置，是最常见的浪费。模型名和价格都以模型广场实时显示为准，接入前先核对一遍，比事后排错省事得多。