调用频率限制

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

​

说明

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

​

术语表

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

• 调用频率：指单位时间内向某一 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 响应：
  {
     "status":1111,
     "wait":5,
     "source":"x5",
     "punish":"deny",
     "uuid":"xxx"
  }
  
• 注意事项
  • 该限制不区分接口类型，单一 IP 的总体流量即为判断依据；
  • 常见于部署在统一网关、NAT 后的多应用共享出口 IP 场景；
  • 使用云服务时，若多个租户共用集群出口 IP，也可能提前触达阈值。

​

规避建议与最佳实践

• 使用代理池或分布式部署：将请求分散至多个不同出口 IP，避免单一 IP 成为瓶颈。
• 引入负载均衡策略：在客户端或网关层实现请求分发，均衡各节点调用压力。
• 增加本地缓存机制：对频繁读取但变化较少的数据（如组织架构、用户信息）进行缓存，减少重复调用。
• 实施熔断与降级逻辑：
  • 检测到 IP 被封禁时，自动切换至备用 IP 或延迟非关键任务；
  • 记录日志并告警，便于运维快速响应。
• 监控与预警：
  • 统计每秒请求数（QPS）趋势；
  • 设置接近阈值（如 8000次/20s）时触发预警通知。