API 报错大全：401、403、429、500、502、524 等状态码原因与解决办法（Claude Code / Codex 通用）
更新于
按状态码整理 API 快连接入时最常见的报错：400、401、403、404、413、429、5xx、524，以及「返回网页」「扣了钱没输出」「越用越慢」这类没有明确状态码的问题。每条都写了原因和你能做的处理。
400 请求参数错误
- 新模型参数限制：claude-sonnet-5-5 / claude-opus-5-5 不接受手动 thinking、强制 tool_choice 等参数，gpt-6.1-sol 的推理强度不能是 none / minimal。详见 model not exist 排查 末尾。这类请求不扣费。
- api_key_in_query_deprecated：把密钥放在了网址参数里（
?key=），改为放在请求头Authorization: Bearer。 - 上游返回的参数错误：请求格式不符合模型要求（例如消息格式不对、图片过大），根据报错原文修改请求。
401 认证失败
密钥无效、没带密钥、密钥被停用，或请求发到了官方地址。完整排查看 401 invalid_api_key 怎么解决。
403 拒绝访问
| 报错里出现 | 原因 | 怎么办 |
|---|---|---|
| insufficient balance / Insufficient account balance | 余额不足。余额较低时并发多个请求，系统会为进行中的请求预留额度，可能还有余额也提示不足 | 充值，或减少同时运行的任务 |
API_KEY_EXPIRED | 密钥过期 | 控制台延长有效期或新建 |
ACCESS_DENIED「Your IP is …」 | 密钥的 IP 白名单不包含当前 IP | 调整白名单 |
GROUP_DISABLED / GROUP_DELETED | 密钥所在分组已停用或删除 | 换一把其他分组的密钥 |
| error code: 1010 | 自写脚本没有带正常的 User-Agent，被接入层拦截（常见于 Python 原生 urllib） | 请求头加一个 User-Agent，例如 MyApp/1.0；用 OpenAI SDK、requests、curl 不受影响 |
404 找不到
- Base URL 多写了路径（例如填成 /v1/chat/completions），或 Claude Code 带了 /v1。看 Base URL 怎么填。
- 模型不在你的分组里：报错含「is not supported by any configured account in this group」。看 model not exist 排查。
413 请求太大
单次请求体积超过上限，通常是对话里堆了很多截图、大文件或超长日志。新开一个会话，或压缩、删减附件后再发。
429 请求过多 / 额度用完
| 报错里出现 | 原因 | 怎么办 |
|---|---|---|
| All available accounts are currently rate-limited | 该分组上游暂时限流 | 稍等重试，或换一个模型 / 分组 |
API_KEY_QUOTA_EXHAUSTED | 这把密钥设置的额度用完了 | 控制台调高额度 |
| requests-per-minute limit exceeded | 每分钟请求数超过限制 | 降低请求频率，代码里加退避重试 |
| Concurrency limit exceeded / Too many pending requests | 同时进行的请求太多 | 减少并发，排队发送 |
INVALID_AUTH_RATE_LIMITED | 短时间内大量错误密钥请求 | 先改对密钥，约 1 分钟后恢复 |
500 / 502 / 503 / 529 服务端或上游繁忙
- 503 Service temporarily unavailable：该分组此刻没有空闲的上游账号（并发占满或短暂冷却），通常几十秒内恢复，稍后重试。
- 529 Overloaded：上游模型过载，稍后重试或换模型。
- 500 / 502：上游临时异常。Claude Code、Codex 会自动重试；持续出现请换模型或联系客服。
- 浏览器里看到「apikl.ai | 502」整页错误：多半是上游账号临时故障，稍后重试；长时间持续请联系客服并附上页面里的 Ray ID。
524 超时，或「扣了钱却没输出」
非流式请求如果超过约 100 秒还没返回，网络链路会先超时断开，你看到 524；但服务端可能已经算完并计费，客户端重试又会再算一次。解决办法：
- 长请求改用流式输出（stream: true），边生成边返回就不会撞超时。
- 改用不经过 CDN 的直连线路：把地址里的
apikl.ai换成dc.apikl.ai（OpenAI 兼容写https://dc.apikl.ai/v1），没有这层超时限制。
没有明确状态码的问题
返回了一段网页 HTML，或报「Unexpected token <」
Base URL 填成了网页地址（例如控制台 https://apikl.ai/keys、文档站 docs.apikl.ai），或写成了 http://、www.apikl.ai（会被跳转，多数客户端不跟随），请求拿到的是网页而不是接口返回。OpenAI 兼容客户端改成 https://apikl.ai/v1，Claude Code 改成 https://apikl.ai。
输出到一半断开、反复「重新连接」
网络抖动或上游短时波动导致流式连接中断。偶尔出现属正常，客户端会自动重连；持续出现可以换模型、检查本地代理软件，或改用直连线路 dc.apikl.ai。
请求很慢是线路问题吗？
不一定。长上下文、深度推理模型、长输出天然更慢。先用一句短问题测试：短问题快、大任务慢，多半是任务本身重；短问题也慢，再看本地网络或换线路。
失败的请求会扣费吗？
认证失败、参数错误、模型不存在、没有可用账号这类在调用模型前就失败的请求不扣费。但如果模型已经开始生成、中途因为超时或断网失败，会按已产生的用量计费，所以长请求请用流式。每笔扣费都可以在控制台的使用记录里核对。
长对话越用越贵？
对话越长，每次请求要带的上下文越多。连续对话时大部分上下文按更便宜的缓存价计费，但离开一段时间后缓存过期，会按全价重算一次。换任务时开新会话，长会话及时压缩。
联系客服前准备什么
- 报错截图或完整报错原文、发生时间。
- 使用的客户端和版本、Base URL、模型名。
- 不要发完整密钥，必要时只发开头和结尾几位。