---
title: "レート制限と並行性制御"
description: "TwexAPI のスループット上限、429 エラーへの対処法、Retry-After ヘッダーの処理、および本番ジョブ向けの安全なバックオフ設計。"
---

TwexAPI は、アカウントの安定運用と上流 Twitter/X データ取得チャンネルの高い可用性を維持するため、レート制限（リクエスト制限）を設けています。一括データエクスポート、AI エージェントの自律ループ、定期実行バッチなどを設計する際は、エラー時に無制限に全力リトライするのではなく、制限規則を尊重した設計を行ってください。

## スループットの目安

TwexAPI はエンタープライズ本番環境の負荷に耐えうるよう設計されています。理想的な条件下における公式ベンチマークでは、クライアントあたり最大 **100 リクエスト/秒 (QPS)** をサポートしていますが、実効スループットはエンドポイントの種別、アカウントのプラン（ティア）、およびプラットフォーム全体のリアルタイム負荷によって変動します。

公開されているスループット値は**ピーク時の上限**であり、すべてのシステム統合で常時最大値を維持すべき目標値ではありません。

| ワークロード | 推奨事項 |
| --- | --- |
| **対話型 AI エージェント** | タスクごとに `explore`（探索）の実行は 1 回に留め、関連する `twexapi_request` をまとめて呼び出します。 |
| **フォロワーエクスポート** | カーソルを用いたページネーションを順次実行します。大規模アカウントではページ間に適切なウェイト（遅延）を挟んでください。 |
| **定期実行ジョブ (Cron)** | ジョブの開始時刻を分散させてください。すべてのワークフローが正時（`:00`）に一斉起動するのを避けます。 |
| **書き込みアクション** | 書き込み頻度は通常の読み取りよりも大幅に低く抑えます。エージェントワークフローでは人間の承認を必須としてください。 |

## 制限に達したときの挙動

許容リクエスト頻度を超過すると、API は HTTP **`429 Too Many Requests`** ステータスコードを返します。レスポンスには、待機推奨秒数を示す **`Retry-After`** ヘッダーが含まれる場合があります。このヘッダーが存在する場合は、指定された秒数以上待機してから次のリクエストを送信してください。

典型的なレスポンス例：

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

MCP プロトコル利用時、`twexapi_request` はツールの実行結果内に同様のステータスコードとエラー詳細を返します。バックオフ（待機）に入る前に、取得済みのデータ行と現在のページネーションカーソルを必ず保持してください。

## 429 復旧チェックリスト

1. **1. バーストトラフィックの即時停止**

    短時間に大量のリクエストを集中送信しているループ処理、Prefect フロー、n8n バッチ、またはエージェントのツールチェーンを一時停止します。

2. **2. Retry-After ヘッダーの確認**

    ヘッダーに指定された秒数待機（スリープ）します。ヘッダーが存在しない場合は 5〜15 秒から開始し、連続して 429 が発生した場合は待機時間を指数関数的に増やしてください。

3. **3. 同一カーソルからの再試行**

    データの欠落や重複を防ぐため、次ページへ進むのではなく、エラーが発生した**同一ページ（同じカーソル）**でリトライしてください。

4. **4. 定常 QPS の抑制**

    ジョブを再開する前に、リクエスト間隔を広げるかバックグラウンドワーカーの並列度を下げて、定常負荷を抑えます。

## バックオフ実装コード例

以下は、`Retry-After` の解析に対応した Python による指数バックオフの標準的な実装パターンです：

```python
import time
import requests

def call_with_backoff(fn, max_attempts=5):
    delays = [5, 15, 45, 120, 300]
    for attempt in range(max_attempts):
        response = fn()
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        # サーバー指定の秒数を優先し、無い場合は指数バックオフリストを使用
        wait = int(retry_after) if retry_after and retry_after.isdigit() else delays[min(attempt, len(delays) - 1)]
        print(f"429 レート制限を検出。{wait} 秒待機して再試行します...")
        time.sleep(wait)

    return response
```

Prefect ワークフローをご利用の場合は、`retry_delay_seconds` パラメータを設定することで同様のバックオフ動作を実現できます — 詳細は [Prefect ガイド](/guides/prefect) を参照してください。

## 429 を回避するための設計パターン

### 1. 順次カーソル取得を徹底し、同一ページの無謀な並列取得を避ける
1 ページ目を 20 並列でリクエストしてもデータ取得は高速化されず、レート制限を即座に消費するだけです。API が明確に並列シャード取得に対応している場合を除き、カーソルに従って順次ページを進めてください。

### 2. 読み取りと書き込みのスケジュール分離
投稿、いいね、フォローなどの書き込み操作に対する制限は、通常の読み取りよりも厳格に設定されています。書き込み処理と検索・プロフィール取得を異なるキューに分離し、書き込み側にはより余裕を持った送信レートを設定してください。

### 3. 静的データの適切なキャッシュ
再利用頻度の高い `user_id`、プロフィール詳細、過去ツイートのメタデータなどはローカルにキャッシュしてください。無駄な重複リクエストを省くことは、レート制限の回避だけでなく、API 課金コストの直接的な削減につながります。

### 4. MCP `explore` の過剰呼び出しを避ける
MCP の `explore` 探索呼び出しも API 使用量としてカウントされます。単一タスクの実行中は、一度特定したエンドポイントの `method` や `path` をキャッシュし、毎ステップごとに繰り返し explore を呼ばないようにしてください。

## ノーコードおよびエージェントプラットフォームでの対応

| プラットフォーム | 推奨パターン |
| --- | --- |
| **[n8n](/guides/n8n)** | 429 エラー検知後に Wait ノードで待機。カーソルはワークフローの Static Data に確実に保存。 |
| **[Zapier](/guides/zapier)** | 組み込みのリプレイ（再試行）と遅延を設定。連続失敗時は運用担当者へアラート通知。 |
| **[Make](/guides/make)** | 429 エラーを Sleep モジュールへルーティングし、待機完了後に HTTP モジュールを再実行。 |
| **[Pipedream](/guides/pipedream)** | 大規模エクスポートを分割し、ワークフローあたりの同時実行ステップ数を制限。 |

各プラットフォームの **Webhook**（Catch Hook、Custom Webhook など）は、エージェント完了後のデータ受け渡し用であり、TwexAPI からのリアルタイムイベント配信ではありません。Webhook 受信後に不足データを追加取得する際は、バックオフを考慮して REST API を呼び出してください。

## MCP と REST API における制限の共通性

MCP プロトコル経由でも標準 REST API でも、同一の TwexAPI アカウントのグローバル制限とクレジット残高を共有します。待機時間を設けずに AI エージェントが `twexapi_request` を連続実行すると、密な SDK ループと同様に 429 が発生します。

長時間を要する大規模データエクスポートでは、ブラックボックスな自律エージェントループに任せるのではなく、**明示的なリトライ設計を備えた標準 REST API または公式 SDK の利用を強く推奨します**。

## レート制限の稼働監視

本番環境では、リクエストごとに以下のメトリクスを記録することを推奨します：

- HTTP レスポンスステータス
- リクエスト先のエンドポイントパス
- 処理中のカーソルまたはページ番号
- 累積リトライ回数
- レスポンスに含まれる `Retry-After` 秒数

単一の API キーまたは特定ワークフローにおいて 429 エラーの発生率が閾値を超えた場合は、速やかに監視アラートを発行してください。

## 関連ガイド

- [エラーハンドリングと復旧ガイド](/guides/error-handling)
- [認証と認可](/authentication)
- [REST API 概要](/api-reference/overview)
- [エージェント MCP ハンドオフ](/mcp/agent-handoff)