api接口超过上限但正常使用避坑:先看是哪一层在报超

接入与开发

接口返回超限却还能正常出结果,这篇帮你分清是额度、频率还是并发在报警,并给出该改代码还是该换通道的判断顺序。

监控突然弹一条「超过上限」,可你手里的请求照样一条条返回,日志也没断。这种时候最容易犯两种错:一种当没看见,等真被掐断时已经过了好几天;另一种立刻改架构、加排队,白折腾一圈。这篇先把「超限还能用」拆成几种情况,再给一套照着走的判断顺序,让你知道哪次该动、哪次可以放着。

监控弹出一条「超过上限」,可你手里的请求照样一条条返回,日志也没断。这种时候最容易犯两种错:一种当没看见,等真被掐断时已经过了好几天;另一种立刻改架构、加排队,白折腾一圈。我见过有团队一看到超限提示就把整条批处理链路改成队列加限流,结果一周后才发现原来是后台额度提醒,代码根本没动过。

这篇先把「超限还能用」拆成几种情况,再给一套照着走的判断顺序。目标很简单:让你知道哪次该动、哪次可以放着,以及动的时候先动哪一格参数。

「上限」这个词,至少指三样东西

软件层面的上限,常见就三种:账户额度(按天按月算的钱或 token)、调用频率(每分钟多少次)、并发数(同时挂几个请求)。三者报错长得像,处理方式完全不同。额度类通常不拦住你,只是后台记账,所以「正常使用」不代表没超;频率和并发才会当场返回错误码。

麻烦在于很多中转站会把错误包装成一段正常文本返回,看着像成功。所以你第一步不是查文档,是确认你看到的那条提示来自哪里:客户端自己统计的、中转站后台的、还是模型厂商原样透传的。来源不同,能改的地方也不同。

额度上限
后台记账型,多数不拦请求,靠用量曲线发现,改的是预算或任务分批
频率上限
按分钟计时,会当场回错误码,改的是请求间隔和退避策略
并发上限
同一时刻挂起的请求数,表现为部分失败部分成功,改的是并发档位

照这个顺序查,别一上来就改代码

  1. 存原始响应把返回的原始 JSON 落盘,检查有没有 error 字段、finish_reason 是不是异常值。别只看代码有没有抛异常,很多超限就藏在「200 但内容不对」里。
  2. 看时间分布把失败请求的时间戳拉出来。集中在一分钟内某个十几秒的窗口,多半是频率或并发;均匀散布全天,更像额度在慢慢磨。
  3. 换 Key 或换通道复跑同样的请求换一个 Key、或换一个通道跑一遍。能过,说明是你的账户侧被限;不能过,再往下查参数和模型。
  4. 最后才动代码先降并发、加退避,别急着换模型或重写链路。改代码之前把改动前的失败率记下来,否则改完你没法判断有没有用。

哪些情况可以放着,哪些必须动

判断分水岭是「结果是否完整」,不是「有没有报错」。这两件事经常不同步,所以得分开看。

现象能不能先放着要动的时候改哪
只是额度接近上限的提醒,请求都正常可以,条件是你能持续看到用量曲线预算或任务分批
单次突发流量被短暂排队,过后恢复可以批次间隔
错误率低且集中在非核心任务上可以把这类任务单独降优先级
同一批请求开始出现空回复或被截断不行先降并发,再查返回内容
流式输出到一半停住不行放宽流式整体超时并加退避
批量任务少量失败、重试又成功不行说明已在边界上,跑大任务会被放大

第三行那种情况特别容易误判:错误率低听着没事,但只要集中在你最在意的任务上,通用流程就不适用了。直接单独立一条链路单独限速,别和批量任务抢同一份配额。

代码这边先改四格参数

  • 并发数:从能稳定跑通的值往下压一档,宁可慢一点也别贴着上限跑;批量任务分批提交,批与批之间留间隔
  • 重试:只对明确可重试的错误做退避重试,别把所有失败都重试,否则额度会被无效请求吃掉
  • 超时:连接超时和整体超时分开设,流式请求的整体超时要放宽,否则你会把正常的慢响应当成失败
  • 日志:请求 ID、模型名、耗时、返回的错误码都记下来,出问题时能对上中转站后台的记录

实际用下来,最常见的误判是超时设太短:流式请求跑到一半被你本地掐了,日志里记成失败,于是你开始怀疑并发,其实是参数填错了那一格。改之前先看一眼整体超时是多少,比翻代码更快。

另一件事是往哪看数字。各家通道的限速口径、错误码含义、后台用量明细都不一样,去 /sites 的通道资料里核对当时的口径,比凭印象猜可靠;接口本身跑得快不快,用 /tools/speed-test 测一轮,排除网络侧干扰再谈限流。

这套判断在什么情况下不好使

第一种:你用的是共享通道或拼车式接口,别人的流量会污染你的观测数据,单看自己的曲线容易误判。这时候看时间分布基本没用,只能靠换通道复跑来对比。

第二种:服务方根本不给用量明细,你只能靠响应特征猜。这种情况下更该做的是换一个有后台可查的通道,而不是继续调参——没有观测数据,调参就是碰运气。想先摸清手上这几个通道的可查程度,到 /rankings 看当时的对比再决定。

下一步把你正在用的通道对一遍:后台有没有用量明细、错误码是否原样透传、限速口径写没写清楚。三条里缺两条,先别忙着改代码,到 /sites 找个可查的通道替换,比调参省事得多。

常见问题

接口提示超过上限,但请求还能返回内容,要不要立刻停掉?

不用立刻停,但要当天查清是哪一类上限。先看返回体里有没有异常字段、结果是否完整,再对一下后台用量。如果只是额度接近上限的提醒,把用量盯紧就行;如果是频率或并发在边界上,压并发加退避,别等它真断。

怎么区分是并发超了还是频率超了?

看失败的时间分布。并发超了往往是一批请求同时发出后集中失败,间隔很短;频率超了更像固定窗口内打满,过了窗口又恢复。把失败请求的时间戳排一下,再对照你代码里提交任务的节奏,基本能对上。

把并发调低是不是就一定安全了?

不一定。并发降下来只是不撞并发上限,额度和频率那两关还在。而且并发太低会让长任务排队,整体耗时上去,成本感知也会变。合理做法是按任务类型分档,核心链路给足并发,批处理慢慢跑。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。