> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 调用频率限制

> 说明服务端 API 的默认调用频率限制机制,涵盖术语表、全局与 IP 维度的限流规则以及规避建议与最佳实践。

为防止应用程序异常调用导致钉钉服务器负载过高，平台对所有服务端 API 接口设置了默认的频率限制机制。当调用频率超过任一维度的限制时，接口将触发限流并返回相应错误信息，影响正常业务执行。

## 说明

调用接口时，系统会同时检测多个限流维度。一旦任一维度（如全局或 IP）超出阈值，请求将被拦截，并返回对应的限流响应。开发者需关注**全局维度**和**IP维度**两个主要限流规则，并在应用设计中加入重试与降级机制，以提升稳定性。

<Note>
  该机制确保了平台整体稳定性，建议开发者合理规划调用节奏，避免集中高频请求。
</Note>

## 术语表

为便于理解后续内容，以下为与限流机制相关的核心术语定义：

* **调用频率**：指单位时间内向某一 API 接口发起 HTTP 请求的次数，通常以“次/秒”衡量。
* **出口IP（公网IP）**：指应用服务器对外访问钉钉 API 时所使用的公网 IP 地址。
* **全局维度**：指以具体 API 接口为单位，统计全平台范围内所有企业、所有应用对该接口的累计调用频率。
* **IP维度**：指基于调用方的公网出口 IP 地址，限制其在单位时间内的总 API 调用量，不区分具体接口。
* **errcode**：钉钉 API 返回的错误码，用于标识调用失败原因；例如`90002`表示触发全局限流。
* **指数退避（Exponential Backoff）**：一种重试策略，每次重试间隔按指数增长（如 1s、2s、4s...），避免持续冲击接口。

## 全局限流维度

* 当前所有企业、所有应用对**同一个接口**的调用频率达到上限后，将触发全局限流。
* 触发后，所有调用方均无法成功请求该接口，返回错误码 `90002`。
* 此限制适用于所有应用类型（包括企业内部应用、第三方企业应用、第三方个人应用等）。
* **适用场景提示**：高并发场景下（如批量数据同步），多个应用同时调用热门接口（如用户管理、消息发送）易触发此限制。
* **权限要求**：调用受保护接口需具备相应权限包授权，且通常需要管理员授权开通相关能力。
* **错误处理建议**：

  * 收到 `errcode: 90002` 时，应立即暂停对该接口的密集调用；
  * 采用指数退避策略进行重试（如等待 1s、2s、4s...）；
  * 可结合事件订阅机制异步处理任务，降低主动轮询频率。

## IP维度限流

* 每个公网出口 IP 地址对所有接口的总调用量限制为：**20秒内最多10000次**。
* 触发限流后，该 IP 将被禁止调用所有接口 **5分钟**。
* 限流不会返回标准 JSON 错误结构，而是返回一个 HTML 页面或如下格式的 JSON 响应：

  ```json lines theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
     "status":1111,
     "wait":5,
     "source":"x5",
     "punish":"deny",
     "uuid":"xxx"
  }
  ```
* **注意事项**

  * 该限制不区分接口类型，单一 IP 的总体流量即为判断依据；
  * 常见于部署在统一网关、NAT 后的多应用共享出口 IP 场景；
  * 使用云服务时，若多个租户共用集群出口 IP，也可能提前触达阈值。

## 规避建议与最佳实践

* **使用代理池或分布式部署**：将请求分散至多个不同出口 IP，避免单一 IP 成为瓶颈。
* **引入负载均衡策略**：在客户端或网关层实现请求分发，均衡各节点调用压力。
* **增加本地缓存机制**：对频繁读取但变化较少的数据（如组织架构、用户信息）进行缓存，减少重复调用。
* **实施熔断与降级逻辑**：

  * 检测到 IP 被封禁时，自动切换至备用 IP 或延迟非关键任务；
  * 记录日志并告警，便于运维快速响应。
* **监控与预警**：

  * 统计每秒请求数（QPS）趋势；
  * 设置接近阈值（如 8000次/20s）时触发预警通知。