> ## 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.

# レート制限

> DingTalk APIの複数次元レート制限ルールを理解し、エラーハンドリング戦略で安定した利用を実現します

アプリケーションの異常な呼び出しによって DingTalk サーバーの負荷が過大になることを防ぐため、プラットフォームはすべてのサーバー API インターフェースにデフォルトのレート制限機構を設定しています。呼び出し頻度がいずれかの次元の上限を超えた場合、インターフェースはレート制限を発動し、対応するエラーメッセージを返します。これにより、通常の業務実行に影響が生じます。

## 概要

API を呼び出す際、システムは複数のレート制限次元を同時に検査します。いずれかの次元（グローバルや IP など）が閾値を超えた時点でリクエストは遮断され、対応するレート制限レスポンスが返されます。開発者は **グローバル次元** と **IP 次元** の 2 つの主要なレート制限ルールに注意し、安定性を高めるためにアプリ設計の中に再試行とフォールバック機構を組み込む必要があります。

<Note>
  この機構によりプラットフォーム全体の安定性が確保されています。開発者は呼び出しペースを合理的に計画し、集中した高頻度リクエストを避けることを推奨します。
</Note>

## 用語集

以降の内容を理解しやすくするため、レート制限機構に関連する主要な用語の定義を以下に示します。

* **レート制限（Call Frequency）**：単位時間内に特定の API インターフェースへ送信される HTTP リクエストの回数を指し、通常「回/秒」で測定します。
* **送信元 IP（パブリック IP）**：アプリケーションサーバーが DingTalk API へ外部アクセスする際に使用するパブリック IP アドレスを指します。
* **グローバル次元**：特定の API インターフェース単位で、プラットフォーム全体におけるすべての企業、すべてのアプリからの累計呼び出し頻度を集計するものを指します。
* **IP 次元**：呼び出し元のパブリック送信元 IP アドレスに基づき、単位時間内の総 API 呼び出し量を制限するもので、具体的なインターフェースは区別しません。
* **errcode**：DingTalk 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）でアラート通知を発動するよう設定します。