レート制限と並行性制御

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

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

スループットの目安

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

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

制限に達したときの挙動

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

典型的なレスポンス例：

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

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

429 復旧チェックリスト

バックオフ実装コード例

以下は、Retry-After の解析に対応した 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 ガイド を参照してください。

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

1. 順次カーソル取得を徹底し、同一ページの無謀な並列取得を避ける

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

2. 読み取りと書き込みのスケジュール分離

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

3. 静的データの適切なキャッシュ

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

4. MCP explore の過剰呼び出しを避ける

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

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

各プラットフォームの 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 エラーの発生率が閾値を超えた場合は、速やかに監視アラートを発行してください。

関連ガイド

• エラーハンドリングと復旧ガイド
• 認証と認可
• REST API 概要
• エージェント MCP ハンドオフ