401 / 403 / 404 / 429：按状态码定位问题
网关错误按层看最快：401 是密钥问题，403 是模型或 IP 权限，404 多为 Base URL 拼错，402 是余额不足，429 是频率或配额触顶。
更新于 2026-11-14 · SageLib 团队 · 标签：troubleshooting、errors
结论要点
- 先看状态码分层，再看错误体的 type 与 message
- 带错认证头 = 401，这是最容易忽略的一条
- 429 只有频率限制，没有并发数限制
排错最省时间的做法是先分层：状态码属于哪一层，就知道该看哪里。
第一层：鉴权与准入（401 / 403 / 404 / 400）
| 状态码 | 典型错误体 | 含义 |
|---|---|---|
| 401 | missing api key |
请求没带密钥 |
| 401 | invalid key format |
前缀不对（应为 sk-） |
| 401 | invalid or disabled api key / api key expired |
令牌无效、被禁用或过期 |
| 403 | model … is not allowed for this api key |
模型不在令牌绑定的模型配置内 |
| 403 | ip whitelist … / ip access control … |
命中 IP 白名单/黑名单 |
| 403 | model_offline |
模型已下架 |
| 404 | not found |
Base URL 拼错，或端点不被该模型支持 |
| 400 | unsupported protocol |
路径既不是协议前缀也不像任何端点 |
鉴权头按协议区分：OpenAI 用 Authorization: Bearer，Anthropic 用 x-api-key，
Gemini 用 x-goog-api-key。带错头 = 401。
第二层：额度（402 / 429）
402 insufficient balance：余额不足，充值后重试；429 rate limit exceeded：单 IP 频率超限；429 user rate limit exceeded：账号级频率超限；- 令牌或令牌组配额触顶：按周期恢复（次日 / 周一 / 月初 1 号）。
第三层：上游转发（502）
502 表示网关到上游这一段没成功，错误体是通用的 upstream error。重试通常有效；
连续出现请把请求时间与模型名给客服。
流式中断不是状态码能回答的
SSE 中途断开时，到「用量日志」详情看结束原因（client_gone / upstream_timeout /
upstream_interrupted / upstream_unreachable），详见
流式输出中断。
完整错误码表见 错误码总览。
参考来源
常见问题
401 与 403 怎么区分？
401 是「身份不明」（没带密钥、前缀不对、令牌被禁用或过期）；403 是「身份明确但没权限」（模型不在令牌的模型配置内、命中 IP 白名单限制、模型已下架）。
429 是并发太多吗？
不一定。网关限制的是频率，同一出口 IP 下的多台机器共用 IP 额度，降频率或错峰更有效。