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 的真实请求,非转述。)

原始响应长这样,可以直接拿你的报错来比对:

json
// 401:不带 Key 访问 /v1/models
{"error":{"message":"lab token denied (request id: 20261121230717838015907wxbuq22F)","type":"new_api_error"}}
json
// 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}",这个数很大

一条命令同时看两个数:

bash
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 大 → 模型推理或排队问题。两者的处理方向正好相反:前者换线路,后者换模型或降上下文长度。

排查顺序:先做这三步

  1. 用 curl 发一个最小请求。 绕开 SDK、绕开业务代码,只有 curl 能复现,就说明问题在代码层之外。接入方式见 快速接入。
  2. 读错误码原文,不要只读状态码。 401、429 内部都有细分,原文里那几个单词就决定了处理方向。
  3. 换一个模型再试一次。 换模型好了是模型或路由问题,换模型一样坏是身份或网络问题。模型清单见 模型清单。

三步都不需要改代码,五分钟内能走完。

参考来源(核对于 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 细分原文写全的公开文档;引用时注明出处,不宣称这是全行业统一文案。

常见问题

lab token denied 是 API Key 错了吗?

是鉴权没通过,但不一定是 Key 写错。三种可能:请求头没有带 Authorization: Bearer 前缀、Key 已被禁用或删除、账户欠费。欠费时更换 Key 无效。

401 和 403 有什么区别?

401 表示没有证明身份,通常是 Key 缺失或错误;403 表示身份已证明但没有权限,例如 Key 无权访问该模型。前者换 Key,后者调整权限或换模型。

429 一直不消失怎么办?

先看错误原文区分类型:含 rate 是频率超限,降低频率并加退避重试即可;含 quota 或 insufficient 是额度耗尽,重试无效,需要充值。额度与价格见 价格与计费。

流式响应中途断开算谁的问题?

看断开前是否收到过 data: 帧。收到过说明上游已开始响应,多为长时间无数据触发中间层超时;一帧未收到说明连接在建立阶段被切断,属于链路问题。

下一步