API 请求速率限制
快速阅读
API 请求速率限制说明的是：客户系统调用呼叫中心 OpenAPI 时，单位时间内允许多少次请求。它是风控与稳定性能力，不是价目，也不等于通话并发或外呼 CPS。
- 开放接口规范（开发者文档「请求频次限制」）：每个接口每秒默认允许 3 次；**数据统计类（如报表类）**每秒默认允许 1 次。超限后立刻重试通常无效。
- 租户配置「API 设置」里，报表类和实时统计类还可以分开调上限。实时统计类页面常见默认 10 次/秒，范围 0～20（以可见值为准），给自建大屏用；不要把 10 次/秒套到所有 OpenAPI。
- 单接口文档若写了更严的频率（例如部分滚动查询约 3 次/秒），以该接口为准。
- 超限返回频次错误。客户端应节流、缓存、合并请求；写操作不要盲目重试。
- 看有没有撞限：用 API 监控；查单次请求：用 API 请求日志；看高频来源：用 API 调用量统计（高阈值，不适合对低频）。
- 预测外呼 CPS、企业外呼 CAPS 是呼叫节奏，不是本页的 OpenAPI 频次。
阅读地图
- 和监控、日志、计费、外呼限流怎么分：读“二”“五”。
- 两层口径（规范默认 vs 租户可调）：读“四”“六”。
- 对接怎么写、怎么验收：读“七”“八”和附录 C。
一、文档说明
对接 CRM、自建看板或批量拉数时，最常见的失败之一是「接口突然频次错误」，却被误判成鉴权失败或平台宕机。本文说明限制对象、在哪配、超限怎么表现、怎么观察和怎么改客户端。
适用：对接 OpenAPI 的技术负责人、实施顾问、需要自建大屏的运维。
签名算法见 鉴权认证。单接口字段见各 OpenAPI / Zenava CLI 专题。金额是否按调用量计费见 计费说明。
二、产品总览
本页对象是开放接口的访问频次，不是某一通正在响的电话，也不是座席登录并发。
密钥对了、参数对了，仍可能因为刷太快被拒。先按「每个接口默认 3 次/秒、统计类默认 1 次/秒」控速；自建大屏再核对租户里的实时统计类上限。
| 能力 | 解决什么 | 典型结果 |
|---|---|---|
| API 请求速率限制（本文） | 单位时间允许多少次 OpenAPI | 超限返回频次错误；降频后恢复 |
| 开放接口规范默认 | 每接口 / 统计类的平台默认 | 一般 3 次/秒；统计类（如报表）1 次/秒 |
| 租户配置 · API 设置 | 报表类 / 实时统计类企业侧上限 | 页面或开通下发的次数/秒 |
| API 监控 | 运行时是否撞限、失败原因 | 能看到频次限制类失败 |
| API 请求日志 | 单次请求是否到达、返回什么 | 排障对 URI 与时间 |
| API 调用量统计 | 哪天哪个客户端 IP 调用特别多 | 发现高频来源（有返回阈值） |
| 外呼 CAPS / 预测 CPS | 每秒能发起多少路呼叫 | 通话节奏，不是 HTTP 频次 |
是否把 API 调用单独计费，以合同为准；本页只讲限制与观察。
三、核心概念
| 概念 | 说明 |
|---|---|
| API 请求速率限制 | 对开放接口按时间窗限制请求次数，保护平台与租户 |
| 每接口默认频次 | 开放接口规范：每个接口每秒默认允许 3 个请求 |
| 数据统计类默认频次 | 开放接口规范：统计类（如报表类）每秒默认允许 1 个请求 |
| 报表类接口频次 | 租户「API 设置」中面向报表查询类开放接口的企业侧上限 |
| 实时统计类接口频次 | 租户侧面向实时统计 / 看板查询的上限；页面常见默认 10 次/秒、范围 0～20 |
| 频次错误 | 超过上限时的业务返回；对接时应当节流处理，不要当成签名错误 |
| 开通下发 | 部分频次可能只读，由开通侧写入，与套餐类额度类似 |
限制是按接口计，不是「整个租户所有 URI 共享一个 10 次/秒」。单接口文档若另有频率，以该接口为准。
四、两层口径怎么一起读
4.1 开放接口规范（平台默认）
呼叫中心 OpenAPI 开发指南「接口规范 · 请求频次限制」现行口径：
- 每个接口每秒默认允许 3 个请求。
- **数据统计类接口（如报表类）**每秒默认允许 1 个请求。
- 超出后，立刻重试通常不能马上恢复；应节流、使用本地缓存、合并/批量请求。
这是对接时的保底假设。智能体等其它开放能力若在各自指南里写了「接口频率限制 3 次/秒」，同样按该指南，不要用看板的 10 次/秒去套。
4.2 租户配置（企业可调）
入口：租户配置 的 API 设置。
| 项 | 要先成立什么 | 不成立时的常见表现 |
|---|---|---|
| 密钥能调通 | 鉴权、权限、Region 正确 | 频次还没轮到，先失败在签名或权限 |
| 规范默认已遵守 | 一般接口 ≤ 3 次/秒；统计/报表类先按 1 次/秒设计 | 未调租户项时密集调用即频次错误 |
| 两类频次已核对 | 报表类、实时统计类页面上限 | 自建大屏或报表拉取仍密集失败 |
| 客户端节奏匹配 | 刷新间隔 × 对该 URI 的并发 ≤ 对应上限 | 高峰突然大批频次错误 |
| 只读额度 | 开通下发的值不能在呼叫配置里「改价」 | 页面改不了，需走开通或支持 |
实时统计类：页面常见默认 10 次/秒，范围 0～20（以可见值为准）。这是给实时看板查询的企业侧上限，不是所有 OpenAPI 的全局配额。报表类企业侧上限以页面可见值为准。
0 次/秒表示该类接口实质上无法调用，配之前要确认不是误操作。
保存后，以新发出的请求为准做验收。不要用一次成功的手工调用证明大屏 1 秒刷新 50 次也能过。
两层同时存在时：先满足规范默认和该接口文档，再看租户是否为报表/实时统计单独放宽或收紧。
五、和周边能力的边界
| 容易混在一起的两件事 | 正确读法 |
|---|---|
| 本页 vs API 监控 | 本页讲规则与怎么配；监控讲有没有撞上、失败长什么样 |
| 本页 vs API 调用量统计 | 统计是按日 / IP 的调用次数（还有返回阈值）；不是限流器本身 |
| 本页 vs 计费 | 限制是风控；是否按调用量出账看合同 |
| 本页 vs 外呼 CAPS / 预测 CPS | 后者限制「每秒发起多少通呼叫」，HTTP 再慢也不会替代通话限流 |
| 本页 vs 座席登录并发 | 登录并发是人能不能再签入，见 FAQ / 租户信息 |
| 本页 vs BYO-LLM 限流 | 那是企业自有模型侧的 QPS，不是呼叫中心 OpenAPI 频次 |
| 系统兼容性 | 未知字段仍应忽略；频次错误是已知业务结果，要单独处理 |
推送 / Webhook 是平台出站到企业，方向相反；出站失败和入站 OpenAPI 频次不是同一条限制。企业接收方自己的限流按企业系统处理。
六、超限之后
典型链路：
客户系统 / CLI / 自建大屏
→ 签名调用 OpenAPI
→ 落在报表类或实时统计类（或其他接口自身频率）
→ 未超限：正常业务响应
→ 超限：返回频次错误（API 监控记为频次限制类失败）对接建议（与开放接口规范一致）：
- 识别是哪一类接口（一般 OpenAPI vs 报表/数据统计 vs 实时统计）。
- 实施请求节流，避免短时间对同一接口打满；错峰；能批量则批量。
- 能缓存的统计结果先缓存，减少重复拉数。
- 超限后不要指望立刻重试成功；读操作可短暂退避后再试。创建任务、改座席等写操作必须幂等或先查再写。
- 用 API 请求日志确认请求已到达，再用监控看是否集中在某一 IP 或某一时段。
具体 HTTP 状态码、错误码字符串以现网接口文档和响应体为准；排障时把响应原文留给支持，不要只报「调不通」。
七、典型场景
7.1 自建实时大屏
刷新过快触发实时统计类频次。把间隔拉到上限以内，并避免多标签、多实例同时打同一租户。验收见 实时运营看板。
7.2 批量拉报表 / 话单
报表类频次独立。分页、滚动查询时遵守该接口自己的频率（含 CLI 注明的约 3 次/秒等）。不要用多进程把同一查询打满。
7.3 管理集成高峰
入职开户、同步队列成员走管理 OpenAPI。频次与写安全见 呼叫中心管理集成。先测试租户，再生产。
八、上线准备与验收
- 客户端先按规范默认控速（每接口 3 次/秒；统计/报表类 1 次/秒），再记下租户页报表类、实时统计类可见上限（含是否只读）。
- 自建大屏按实时统计类上限设计刷新和多实例合计。
- 造一次超限：确认返回是频次错误，而不是把密钥判废。
- 降频后确认恢复。
- API 监控能看到对应失败类型；必要时对 API 请求日志。
| # | 场景 | 期望 |
|---|---|---|
| 1 | 低于上限的只读查询 | 成功 |
| 2 | 超过实时统计类上限 | 频次错误；降频后成功 |
| 3 | 鉴权错误 | 与频次错误可区分 |
| 4 | 多实例大屏 | 合计不超过上限 |
| 5 | 写操作遇频次错误 | 不重复创建对象 |
九、常见问题
所有 OpenAPI 都是 10 次/秒吗？
不是。开放接口规范默认是每个接口 3 次/秒，统计/报表类 1 次/秒。10 次/秒只是租户「实时统计类」的常见页面默认，给看板查询用。
调高上限是不是就能当无限调用？
实时统计类可配上限通常到 20 次/秒。再高需看开通是否允许，且仍受平台保护。不要用调上限代替合并请求。
CLI 会不会也受限？
会。Zenava CLI 走同一套 OpenAPI。脚本循环同样要控速。
调用量统计里没有我的 IP，是不是没撞限？
统计有返回阈值（例如次数过低不出现）。低频失败请查 API 请求日志和监控。
和「系统兼容性」冲突吗？
不冲突。兼容性要求忽略未知字段；频次错误是明确失败，应停止或减速，而不是当成功。
十、边界说明
本文不列出全量 URI 的逐条 QPS 表，也不替代合同中的调用量计费条款。
附录 A：相关文档
附录 B：术语（本篇）
| 中文 | 英文主词 | 说明 |
|---|---|---|
| API 请求速率限制 | API Request Rate Limit | 页名跟线上 |
| 每接口默认频次 | per-API default rate limit | 规范：每接口 3 次/秒 |
| 数据统计类默认频次 | statistics API default rate limit | 规范：统计/报表类 1 次/秒 |
| 报表类接口频次 | report API rate limit | 租户 API 设置 |
| 实时统计类接口频次 | realtime-statistics API rate limit | 租户页常见默认 10 次/秒 |
| 频次错误 | rate-limit error | 超限业务返回 |
附录 C：实施检查清单
- 一般调用已按每接口 3 次/秒设计；统计/报表类先按 1 次/秒
- 已记录租户页报表类、实时统计类可见上限
- 自建大屏 / 脚本刷新落在上限内（含多实例合计）
- 超限响应与鉴权失败可区分
- 写操作有幂等或回查，不因重试重复建对象
- API 监控能看到频次限制类失败
- 个别滚动查询等接口已按该接口文档控速
- 未把外呼 CAPS / CPS 当成 HTTP 频次
Updated about 2 months ago