> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md).

# レート制限

外部 API は、APIキーごとに独立してリクエスト数を制限しています。このページを参考に、上限に余裕をもって収まるクライアントを設計し、`429` が返ったときに適切に処理してください。

## 制限の仕組み

制限は「**バースト枠**」と「**持続的なリクエスト速度**」の組み合わせです。一時的な短い集中は問題ありませんが、長く続く集中は抑制されます。

* **少数のリクエストを間を空けずに連続で**送れます。
* バースト枠を使い切ると、以降は**おおむね毎秒1リクエスト**の速度で受け付けられます。
* しばらくリクエストを止めると、バースト枠が回復し、再び使えるようになります。

制限は **APIキーごと**です。お客様のキーの利用状況は、他のお客様や、お客様自身の別のキーとは分けて扱われます。

{% hint style="success" %}
**一定期間の累計や1日あたりの上限ではありません。**\
ダッシュボードが複数のエンドポイントを同時に読み込むような短い集中は許容しつつ、基盤の安定性に影響する大量のリクエストが続くのを防ぐための仕組みです。
{% endhint %}

## 現在の既定値

| 項目     | 既定値                          |
| ------ | ---------------------------- |
| バースト枠  | 連続で送れる **10 リクエスト**          |
| 持続的な速度 | バースト枠を使い切ったあとは **毎秒約1リクエスト** |

この既定値は、ユーザーの一括登録、定期的なエクスポート、ダッシュボードなど、一般的な連携に合わせたものです。より多くのリクエストが必要な場合は、APIキーの上限の引き上げについて[弊社にお問い合わせください](https://www.digitalhumans.com/jp/contact)。

## リクエストが拒否されたとき

上限を超えると、API は次のように応答します。

* **ステータス**: `429 Too Many Requests`
* **ヘッダー**: `Retry-After: <秒数>`（再試行までに待つ時間）
* **ボディ**:

  ```json
  { "error": "Rate limit exceeded. Try again later." }
  ```

`Retry-After` ヘッダーに従ってください。次のリクエストが成功するまでに待つべき時間が示されています。

## クライアントの設計

### 一括処理（大量のユーザー追加、大きなエクスポートのページ送りなど）

持続的に繰り返す処理では、**毎秒1回程度**の間隔でリクエストを送ってください。開始直後はバースト枠の分まですぐに送り、その後は毎秒約1回のペースに落とします。

{% tabs %}
{% tab title="Python" %}

```python
import time
import requests

for page in range(1, 100):
    response = requests.get(
        f"{BASE_URL}/users/page/{page}", headers=headers, params={"limit": 25}
    )

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", "1"))
        time.sleep(retry_after)
        continue  # retry the same page

    response.raise_for_status()
    # process page …
    time.sleep(1)  # stay under the sustained rate
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

for (let page = 1; page <= 100; page++) {
  let response = await fetch(`${BASE_URL}/users/page/${page}?limit=25`, { headers });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') ?? '1', 10);
    await sleep(retryAfter * 1000);
    page--; // retry the same page
    continue;
  }

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  // process page …
  await sleep(1000); // stay under the sustained rate
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
上の Python の例では、`429` のあと `continue` で次のページに進むため、同じページは再試行されません（コメントの「retry the same page」と動作が一致しません）。同じページを再試行するには、`while` ループで同じ `page` を繰り返すように書き換えてください。
{% endhint %}

### `429` が返ったときの再試行

必ず次のようにしてください。

1. **`Retry-After` ヘッダーを読み**、その時間以上待ってから再試行します。
2. 複数のクライアントを並行して動かしている場合は、**わずかなゆらぎ（ジッター）を加え**（例: 0〜500 ミリ秒）、すべてが同じ瞬間に再試行しないようにします。
3. `429` が続く場合は**指数バックオフ**を使います。待ち時間を毎回2倍にし、適当な上限で止めます。

### トレーニングを生成する場合

[`POST /immersive-training/generate`](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md) は、性質上時間がかかります。1回の呼び出しで AI による生成を何段階も実行するため、30〜90 秒かかります。これほど遅い呼び出しなら、順番に1件ずつ実行する限りバースト枠で十分足り、上限に近づくことはありません。

一方、複数件を同時に実行すると上限に達します。1件ごとに1分以上枠を占有し、このエンドポイントには同時実行数の上限が別に設けられていないためです。お客様の側で間隔を空け、クライアントのタイムアウトは 120 秒以上にしてください。

### そもそも `429` を発生させないために

* **ページ送りは順番に実行する。** すべてのページを並行して取得せず、短い間隔を空けて1ページずつ処理します。
* **あまり変わらないデータはキャッシュする。** 参照データ（学習ドメイン、`persona-config`、タグ）はほとんど変わりません。レコードごとではなく、処理1回につき1度だけ取得してください。詳しくは「[参照データ](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md)」をご覧ください。
* **まとめて送れるエンドポイントではまとめる。** `POST /users/add` はメールアドレスの配列を受け付けるため、ユーザーごとに1リクエスト送る必要はありません。

## 早見表

| 項目         | 値                                                         |
| ---------- | --------------------------------------------------------- |
| 適用範囲       | APIキーごと                                                   |
| 方式         | バースト枠＋持続的な速度                                              |
| バースト（既定）   | 10 リクエスト                                                  |
| 持続的な速度（既定） | 毎秒約1リクエスト                                                 |
| 拒否時のステータス  | `429 Too Many Requests`                                   |
| 再試行の目安     | レスポンスヘッダー `Retry-After`（秒）                                |
| 上限の引き上げ    | [弊社にお問い合わせください](https://www.digitalhumans.com/jp/contact) |
