错误码总表

网关全部错误码的完整清单。message 一列是服务端返回的原文，可以直接拿来做字符串比对；处置建议见错误处理与重试。

🔢

编码规则：HTTP 状态码 + 2 位序号

42905 = 429 + 序号 05。所以看到码就知道 HTTP 状态。唯一的例外是 41301—— 413 是三位数状态码里的特例，它的完整形态就是 413 + 01。

判断是不是网关错误，看 error.type 是否为 "gateway_error"；不是的话就是上游厂商的原样透传，本表不适用。

400 请求参数

code	message	说明与处置
40000	invalid request body	请求体不是合法 JSON。检查转义与 `Content-Type`。
40001	api_key is required	没取到密钥。最常见成因是用了 `x-api-key`——兼容端点只读 `Authorization: Bearer`。
40002	model_id is required	`model` 缺失。Gemini 端点是路径里没解析出模型名。
40003	content is required	请求体为空或读取失败。Gemini 端点上也用于「动作不受支持」。
40004	protocol is required	协议未能判定。走标准端点不会出现。
40005	上下文超过模型限制，请开启新会话或压缩上下文！	已停用（2026-08-24 起不再下发）。此前用于「要求的输出长度含思考预算超过该模型输出上限」，在入口一次判定、不发上游。现已改为不拦截：请求照常转发，由上游厂商裁定并返回其原始错误。号段保留不复用，客户端已有的判断分支可以留着，只是不会再命中。

🈶

个别 message 是中文，这是有意的

表里其余条目都是英文技术描述，只有 40005 和 42906 下发中文——因为客户端通常会把 message 原样显示给终端用户看，这两条是用户自己能处理的情况。（40005 已于 2026-08-24 停用，现在实际会遇到的只剩 42906。）

code	message	说明与处置
40201	no active subscription	没有生效中的订阅。
40202	api billing access not enabled	未订阅且未开「API 扣费访问」。新账号的第一个错误基本都是它。账号未实名时，中文提示里会追加实名引导。见计费。
40203	model access restricted	模型准入不足（认证等级或套餐等级）。实际下发的是中文原因，见模型、准入与回退。

code	message	说明与处置
41301	request body too large	请求体超过 100 MiB。基本只有 base64 图片/文件会触碰。拆小或改用文件引用。

code	message	说明与处置
42901	concurrency limit exceeded	并发超限。是拒绝不是排队，降低客户端并发。
42902	rpm limit exceeded	分钟级请求数超限。策略层的请求次数/图片/视频/累计金额也都用这个码，所以它不一定真的是「每分钟」。以 `Retry-After` 为准。
42903	rph limit exceeded	小时级请求数超限（上游链路层）。
42904	rpd limit exceeded	天级请求数超限（上游链路层）。
42905	tpm limit exceeded	Token 用量超限。请求数没超也可能先撞它——通常是单次请求太长。
42906	subscription quota exhausted	订阅/订阅外额度用完。订阅用户收到的是中文文案，会说明维度、档位与恢复秒数。补额度前重试无意义。
42907	points insufficient	积分不足。余额有钱也可能报它——需要开启自动兑换或手动兑换。
42908	all upstreams temporarily rate-limited, please retry later	所有可用上游都在限流/失败冷却中。临时态，带 `Retry-After`，退避后重试即可。

429 响应会附带 Retry-After 与 X-RateLimit-* 头，详见限流、配额与并发。

code	message	说明与处置
50201	no available upstream for this model	该模型没有可用凭证。客户端侧最常见的成因是模型名写错。名字没错却持续出现，是平台配置问题，重试无效，请反馈。
50202	upstream url not configured	配置问题，重试无效。
50203	upstream api key not configured	配置问题，重试无效。
50204	upstream unreachable	网络问题，可退避重试 1–2 次。
50205	proxy connection failed	代理连接失败，可退避重试。
50206	upstream url invalid	配置问题，重试无效。
50207	upstream dns resolve failed	DNS 抖动，可退避重试。
50208	upstream tls handshake failed	TLS 握手失败，可退避重试。
50209	router not found	无可用路由，配置问题。
50230	health status unavailable	健康状态加载失败。
50233	proxy not found	凭证指定了代理但代理配置查不到。
50234	policy not found or disabled	凭证的限制策略缺失或被禁用。与代理无关——此前这个场景复用 `50233`，会把排查引向代理方向，故拆出独立码。

✅

分清 42908 与 50201

42908 = 有上游，但都在冷却，等等就好； 50201 = 压根没有可用上游，等多久都不会好。两者的处置完全相反，别混。

code	message	说明与处置
50401	upstream timeout	上游超时。可退避重试；同时考虑调低 `max_tokens`，或改用流式以避免长时间无输出。

code	message	说明与处置
50001	internal error	不可预期的内部错误。重试一次；持续出现请带上时间与请求特征反馈。
50002	route config load failed	路由配置加载失败。

计费资格判定失败时也会返回 500，message 为 计费资格校验暂不可用，请稍后重试——这是刻意的 fail-closed：判不了就拒，避免产生无法计费的调用。见计费、积分与订阅。

请求成功路由到上游后，厂商返回的错误原样透传——状态码与响应体都是厂商的原始格式， error.type 不会是 "gateway_error"。这类错误请查对应厂商的文档。好处是你现有的官方 SDK 错误处理代码可以直接复用。