API 报 401、429、超时分别是什么问题:一份排查顺序表
API 报错先分三类:401 是身份问题,429 是频率或额度问题,超时是链路或推理问题。先读原文再改代码。(2026-11-21)
发布于 · 更新于
一句话分清三类
| 状态码 | 本质是什么 | 先查什么 | 典型错误码 |
|---|---|---|---|
| 401 | 你是谁,没证明成功 | Key 有没有带对、是否被禁用、账户是否欠费 | lab token denied |
| 429 | 你请求太多,或额度用完了 | 频率、并发、余额 | Throttling.RateQuota、insufficient_quota |
| 无响应 / 超时 | 请求没走到,或走得慢 | 网络连通、连接是否中断、首字节耗时 | 无(客户端异常) |
| 5xx | 上游服务本身出问题 | 是否可重试 | InternalError、ServiceUnavailable |
记住这张表的顺序:先看状态码,再看错误码原文,最后才动代码。 绝大多数排查浪费在「不看原文直接改参数」。
第一层:你在 KL API 上会看到的原文
这一层是我们自己网关返回的,和上游厂商的错误不是一套词。搜报错时按这一层的原文搜。
| 状态码 | 网关返回原文 | 触发条件 | 处理 |
|---|---|---|---|
| 401 | lab token denied (request id: ...),type 为 new_api_error |
Key 缺失、无效、被禁用 | 检查请求头 Authorization: Bearer,核对 Key |
| 404 | Invalid URL (GET /v1/chat/completions),type 为 invalid_request_error |
请求方法或路径不对(如用 GET 调对话接口) | 换 POST,核对路径 |
| 404 | Invalid URL (POST /xxx) |
路径拼错或模型名拼错 | 对照 模型清单 核对模型名 |
(以上原文来自 2026-11-21 对 agent.kl-api.info 的真实请求,非转述。)
原始响应长这样,可以直接拿你的报错来比对:
// 401:不带 Key 访问 /v1/models
{"error":{"message":"lab token denied (request id: 20261121230717838015907wxbuq22F)","type":"new_api_error"}}
// 404:用 GET 调对话接口
{"error":{"message":"Invalid URL (GET /v1/chat/completions)","type":"invalid_request_error","param":"","code":""}}
报错里的 request id 有什么用
lab token denied (request id: 20261121230717838015907wxbuq22F) 里那串 request id 是这次请求的唯一标识。提工单时把它一起给出,对方能直接定位日志,比一句「我调不通」有效得多。养成看到报错就顺手复制 request id 的习惯。
第二层:上游透传的原始错误码
Key 正确、请求合法时,问题可能出在上游。这一层的原文是厂商的错误码,会原样透传,标注来源是哪家文档——它们不一定是 OpenAI 的官方文案,别混着说。
| 情形 | 典型原文 | 怎么确认 |
|---|---|---|
| Key 无效(上游判) | invalid_api_key(InvalidApiKey) |
出现厂商错误码说明请求已到上游 |
| 账户欠费 | Access denied, please make sure your account is in good standing.(Arrearage) |
看余额,不是看 Key |
| 频率超限 | Requests rate limit exceeded, please try again later.(Throttling.RateQuota) |
降频 + 退避重试 |
| 额度耗尽 | insufficient_quota(Throttling.AllocationQuota) |
充值,重试无用 |
| 断连 | Client disconnected before task finished!(ClientDisconnect) |
检查中间层超时 |
| 上游故障 | InternalError、ServiceUnavailable |
可重试,配合退避 |
判断当前卡在哪一层:报错里出现 new_api_error,是网关层,问题在你的请求或账户;出现上游厂商错误码,说明请求已经穿过去了,问题在模型侧。
401:身份问题,分四种
401 不是一种错,是四种。原文不一样,处理方式也不一样。
| 情形 | 典型原文 | 怎么确认 |
|---|---|---|
| Key 写错或没带 | lab token denied(网关层) |
检查 Authorization: Bearer 前缀是否漏了 |
| Key 被禁用或删除 | 同为鉴权失败,但该 Key 在控制台已不存在 | 控制台里看 Key 状态 |
| 账户欠费 | Access denied, please make sure your account is in good standing.(Arrearage) |
看余额,不是看 Key |
| 协议头格式不对 | 鉴权失败 | 检查是否把 Key 放进了 query 而不是 header |
第三种最容易被误判成 Key 错。 原文里出现 account、billing、good standing 这类词,就直接去查余额,别在 Key 上浪费时间。
429:频率问题还是额度问题
429 有两种,混在一起查会一直查不出原因。
| 类型 | 典型原文 | 本质 | 处理 |
|---|---|---|---|
| 频率超限 | Requests rate limit exceeded, please try again later.(Throttling.RateQuota) |
单位时间请求数或 token 数超了 | 降频、加退避重试、拆小请求 |
| 额度耗尽 | insufficient_quota(Throttling.AllocationQuota) |
钱或配额用完了 | 充值,重试无用 |
判断方法:原文里出现 rate 是频率,出现 quota / insufficient / balance 是额度。前者等一等能过,后者等多久都过不去。
重试要带退避:每次失败后间隔乘以 2,并设最大重试次数和总耗时上限。无限重试只会把限流拖得更久。
用错 Key 连打几次,返回的却是 429
这是最容易误判的一种:Key 填错了,但网关回的不是 401,而是 429:
You have used invalid tokens multiple times, please wait 120 seconds before trying again
原因是同一 IP 连续用无效 Key 会触发临时封禁,封 120 秒。看到这句不要去查额度或频率,那 120 秒是等出来的:先确认 Key 本身对不对,等冷却结束再试。第一次看到 401 lab token denied 时就该停下来核对,而不是反复重试。
超时:链路问题还是推理问题
超时的三种形态,处理方式完全不同。
| 现象 | 说明 | 怎么测 |
|---|---|---|
| 连不上(DNS / 端口不通) | 请求根本没发出去 | curl -w "%{time_connect}",连接耗时异常 |
| 连接建立后中断 | 上游或代理把连接切了 | 服务端原文 Client disconnected before task finished!(ClientDisconnect) |
| 首字节很慢 | 连上了,模型在算 | curl -w "%{time_starttransfer}",这个数很大 |
一条命令同时看两个数:
curl -o /dev/null -s -w "connect=%{time_connect}s ttfb=%{time_starttransfer}s\n" \
https://agent.kl-api.info/v1/models \
-H "Authorization: Bearer $KL_API_KEY"
connect 大 → 网络问题;ttfb 大 → 模型推理或排队问题。两者的处理方向正好相反:前者换线路,后者换模型或降上下文长度。
排查顺序:先做这三步
- 用 curl 发一个最小请求。 绕开 SDK、绕开业务代码,只有 curl 能复现,就说明问题在代码层之外。接入方式见 快速接入。
- 读错误码原文,不要只读状态码。 401、429 内部都有细分,原文里那几个单词就决定了处理方向。
- 换一个模型再试一次。 换模型好了是模型或路由问题,换模型一样坏是身份或网络问题。模型清单见 模型清单。
三步都不需要改代码,五分钟内能走完。
参考来源(核对于 2026-11-21)
- KL API 网关 401 原文:
GET https://agent.kl-api.info/v1/models(不带 Key)实测 - KL API 网关 404 原文:
GET https://agent.kl-api.info/v1/chat/completions实测 - 上游错误码原文(
InvalidApiKey、Arrearage、Throttling.RateQuota、Throttling.AllocationQuota、ClientDisconnect、InternalError):https://www.alibabacloud.com/help/tc/model-studio/error-code-start(文档更新时间 Nov 15, 2026) curl -w的time_connect/time_starttransfer语义:curl 官方手册
错误码文档以阿里云百炼为例,因为它是少数把 401/429 细分原文写全的公开文档;引用时注明出处,不宣称这是全行业统一文案。