Twitter (X) API レート制限ガイド — 15分上限・429 エラー・回避パターン
Twitter (X) API を本番運用すると、ほぼ全てのチームが 429 Too Many Requests に一度はぶつかります。原因は単純に "呼びすぎ" だけではなく、15分単位の per-endpoint cap、ユーザー文脈とアプリ文脈の cap の違い、Tier ごとの cap 差、そして 2026年に X が pay-per-use モデルへ移行した後に新設された spending limits など、複数のレイヤーが絡みます。
本記事では docs.x.com の公式仕様 (2026-05 確認) を基準に、Twitter (X) API のレート制限を endpoint 別の数字 + 失敗時の挙動 + 回避パターン の3層で整理します。さらに、第三者 API である TwitterAPI.io が 15分単位の cap を持たず、代わりに ユーザー設定の spending limits でコストを制御する設計を採っている理由と、両者をどう使い分けるかをまとめます。
実装例は Python (requests + token-bucket リミッター)。コピペで動く形で、429 を捕捉して exponential backoff + jitter を入れる典型パターンを書いています。
そもそも "レート制限" とは何を指すのか
Twitter (X) API でいう "レート制限" は実は 2 軸 × 2 軸 = 4 種類 あります。これを混同するとレート制限の挙動が予測できなくなります。
軸 A: 集計窓 — 15分窓 (短期 burst 制限) と 月単位 (使用量 / 支出 cap)。短期窓は "叩きすぎたら即 429"、月単位は "使った分だけ請求、または設定上限で停止"。
軸 B: 適用範囲 — User context (OAuth ユーザートークン単位) と App context (アプリの bearer token 単位)。同じ endpoint でも、user context で 75/15min、app context で 450/15min など、別の上限を持つことがあります。
つまり同じ "レート制限" でも、(short window + user)、(short window + app)、(long window + user)、(long window + app) の4種が独立に存在します。本番運用では4つすべてをモニタリングしないと、たまにある特定パターンの 429 が説明できなくなります。
公式 Twitter (X) API の endpoint 別 cap (2026 最新)
docs.x.com の公式 rate-limit ページに掲載されている主要 endpoint の cap を抜粋します。これは Free / Basic / Pro / Enterprise tier 共通の "short window" 値で、月単位 cap や spending limits とは独立です。
Tweets を読む系:
Users を読む系:
書き込み系 はさらに別軸で、POST /2/tweets は 200/15min/user + 100/24h/user の 2 重 cap、DELETE /2/tweets/:id は 50/15min/user — 短時間 burst を許さない設計です。
この表で見えにくいが運用上重要な点: followers の 15/15min は、1ユーザーあたり最大 1000フォロワーを 15分間に 15ページ = 最大 15,000 followers/15min。100万フォロワーのアカウントを全件取得するには 約16時間 かかります。これは公式 cap の物理的下限です。
429 エラーの中身と recovery パターン
429 を返したとき、X API は x-rate-limit-reset ヘッダー に次回利用可能になる Unix timestamp (秒) を含めます。これを見て待つのが正攻法です。素朴な sleep(60) では reset 前に再 hit したり、reset 後すぎたり、いずれにせよ非効率です。
また 429 にも複数バリアントがあります。Type 1: short-window cap (即時、x-rate-limit-reset で15分以内の復旧)。Type 2: monthly cap exceeded (pay-per-use に移行する前の旧 Tier で発生、x-rate-limit-reset が翌月初を指す)。Type 3: spending limits hit (2026 新設、ユーザー設定の月支出上限到達 — x-rate-limit-reset ではなく 403 が返ることもある)。
典型的な recovery パターン (token-bucket + exponential backoff):
- リクエスト前に in-memory の token-bucket を確認。トークン不足なら次回 refill まで time.sleep()
- 429 が返ったら、まず x-rate-limit-reset を読み、その時刻まで sleep
- reset 後の最初のリクエストにも余裕を持たせ、jitter を入れて他のクライアントとの衝突を回避
- 同一 endpoint に対して 連続 3 回 429 が出たら circuit breaker を発動して 30分間そのワーカーを停止 — wedged な状態を防ぐ
TwitterAPI.io の設計 — 15分 cap がない代わりに何があるか
TwitterAPI.io (第三者 X API) は、endpoint 別の 15分 cap を設定していません。代わりに以下の3層で運用を予測可能にします。
1. Pay-per-call ($0.00015 / read) — 公式 X API ($0.005 / read) の約 1/33 の per-call cost。コストは線形に積み上がるが "突然 429 で止まる" タイプの予測不能性はない。
2. Spending limits (ユーザー設定) — billing cycle 単位で支出上限を設定可能。設定額に到達すると新規リクエストが拒否される (これは公式 X API の spending limits と同じ概念)。
3. Internal fair-use throttling — abusive な burst (1秒あたり数百リクエストなど) は内部的に throttling される。通常運用では遭遇しない。詳細は API ドキュメントの "Best practices" に記載。
つまり、TwitterAPI.io 側で 429 が出るのは spending limits を ユーザー自身が設定したから か、fair-use throttling を引いたから のどちらかで、公式 X API のように 15分単位で予測不能に 429 が来ることはありません。
運用上の意味: 大規模 crawler や real-time モニターを書く場合、TwitterAPI.io の方が rate-limit 設計を読まずに済む — 純粋にコストとデータ可用性の2軸だけで意思決定できる。これは特に start-up / 個人開発で大きな差になります。
Python 実装例 — token-bucket + 429 ハンドリング
以下は公式 X API を使う前提の token-bucket リミッター + 429 ハンドリングの最小実装です。/2/users/:id/tweets (timeline 取得) を 900/15min user context で叩く想定。
実装のポイント:
- TokenBucket は in-memory で、プロセス再起動時にリセット (本番では Redis などに移すべき)
- x-rate-limit-reset を読んで sleep する分岐を、リクエストの 後 ではなく 429 を受けた瞬間 に挟む
- backoff は jittered exponential (Full Jitter, https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
- 連続 3 回 429 で circuit breaker — 同じ endpoint に対する次のリクエストを 30 分間停止
もし TwitterAPI.io に切り替えるなら、この token-bucket 全体が不要になります — そこが "15分 cap がない" 設計の運用上のメリットです。
endpoint 別 cap 早見表 — 公式 vs TwitterAPI.io
本記事の主要 endpoint について、両 API の short-window cap を1表にまとめます。
実用上の判断軸: Followers list を大量に取得する用途 (audience analytics、KOL discovery 等) では、公式 X API の 15/15min cap が物理的な下限を作る。TwitterAPI.io は cap がない分、コスト試算だけで運用設計できます。
TwitterAPI.io への移行 — 5 分のクイックスタート
実際に TwitterAPI.io へ移行するときの手順は最小限です。
1. アカウント作成 — Google サインインのみ。OAuth 4 キーや署名は不要。新規ユーザーには $10 voucher が付与される (個人開発で数か月分の試用に相当)。
2. API キー取得 — ダッシュボードから X-API-Key を発行。これを HTTP ヘッダーに X-API-Key: <key> として渡す。
3. エンドポイント置換 — https://api.twitter.com/2/... → https://api.twitterapi.io/twitter/... への単純な URL 置換。レスポンスフォーマットは X API 互換のため、ほぼ無改修で動きます。
4. OAuth ロジック削除 — 4 キー (consumer key / consumer secret / access token / access token secret) + リクエスト署名生成のコードが全部不要になる。実コードでは 50-100 行の削減が一般的です。
5. (任意) spending limits 設定 — 月の予算を決め、ダッシュボードから設定。設定額に到達するとリクエストが拒否され、コスト予測性が確保されます。
この5ステップで、15分単位の rate-limit 設計について考える必要がなくなります。/2/users/:id/followers のような cap が物理的に効くケースでは、TwitterAPI.io 側で取得スピードが ~33× 速くなることもあります (公式 cap がない + per-call cost が低い両方の効果)。
# pip install requests
import time
import random
import requests
BASE = "https://api.twitter.com/2"
BEARER = "YOUR_X_API_BEARER_TOKEN"
class TokenBucket:
"""Simple in-memory token bucket — 900 tokens / 15 min for /users/:id/tweets."""
def __init__(self, capacity, refill_seconds):
self.capacity = capacity
self.refill_seconds = refill_seconds
self.tokens = float(capacity)
self.last = time.time()
def take(self):
now = time.time()
elapsed = now - self.last
self.tokens = min(self.capacity, self.tokens + elapsed * (self.capacity / self.refill_seconds))
self.last = now
if self.tokens >= 1:
self.tokens -= 1
return 0 # no wait
wait = (1 - self.tokens) * (self.refill_seconds / self.capacity)
time.sleep(wait)
self.tokens = 0
self.last = time.time()
return wait
def get_user_timeline(user_id, bucket, max_attempts=5):
headers = {"Authorization": f"Bearer {BEARER}"}
url = f"{BASE}/users/{user_id}/tweets"
for attempt in range(max_attempts):
bucket.take()
r = requests.get(url, headers=headers, timeout=10)
if r.status_code == 200:
return r.json()
if r.status_code == 429:
# honor server-told reset time
reset = int(r.headers.get("x-rate-limit-reset", time.time() + 60))
sleep_for = max(0, reset - time.time()) + random.uniform(0.5, 3.0) # jitter
print(f"429: sleeping {sleep_for:.1f}s until reset")
time.sleep(sleep_for)
continue
if r.status_code in (500, 502, 503, 504):
backoff = (2 ** attempt) + random.uniform(0, 1)
print(f"{r.status_code}: backoff {backoff:.1f}s")
time.sleep(backoff)
continue
r.raise_for_status()
raise RuntimeError("max attempts exceeded")
if __name__ == "__main__":
# 900 tokens / 15 min (user-context cap for /users/:id/tweets)
bucket = TokenBucket(capacity=900, refill_seconds=900)
user_id = "REPLACE_WITH_USER_ID"
data = get_user_timeline(user_id, bucket)
print("got", len(data.get("data", [])), "tweets")
よくある質問
Twitter (X) API のレート制限はいくつですか?
endpoint 別に異なります。代表的な値: tweets/search/recent は 180/15min (user) / 450/15min (app)、users/:id/tweets は 900/15min (user) / 1500/15min (app)、users/:id/followers は 15/15min (両方)。完全な表は docs.x.com の rate-limit ページに掲載されています。本記事の "endpoint 別 cap 早見表" セクションも参照してください。
429 Too Many Requests が返ったらどうすればいいですか?
(1) x-rate-limit-reset ヘッダーを読み、その Unix timestamp まで sleep する。(2) 復帰後の最初のリクエストに jitter (0.5-3 秒の random sleep) を入れる。(3) 連続 3 回 429 が出たら circuit breaker を発動し、同 endpoint への新規リクエストを 30 分間停止する。本記事の Python 実装例で完結する形のコードを掲載しています。
TwitterAPI.io にはレート制限がありませんか?
公式 X API のような "endpoint 別 15分 cap" は設定されていません。代わりに (1) pay-per-call ($0.00015/read) によりコストが線形に積み上がる、(2) ユーザー設定の spending limits により予算で停止できる、(3) 内部 fair-use throttling が abusive な burst を制限する、という3層構造です。通常運用で 429 を見るのは spending limits の設定時のみです。
User context と App context の cap の違いは何ですか?
User context は OAuth ユーザートークン単位の cap で、特定のユーザーが行う操作 (自分の DM 取得、自分の followers 取得など) に適用されます。App context は アプリ全体の bearer token 単位の cap で、public data の取得 (任意のユーザーの public tweets など) に使われます。同じ endpoint でも user / app で別の上限値が設定されているのが標準です。
月の合計使用量に上限はありますか?
2026 年現在の pay-per-use モデルでは、X 公式仕様には platform-side のハードキャップは設定されていません (docs.x.com 確認)。代わりに ユーザー側の spending limits で billing cycle 単位の最大支出額を設定する仕組みです。旧 Basic ($200/月) / Pro ($5,000/月) / Enterprise tier には月単位の使用量上限がありましたが、これらは現在 contact-sales 専用となり新規には pay-per-use のみが提供されます。
Followers list の取得が遅すぎる場合の対処法は?
公式 X API の users/:id/followers は 15/15min × 1000/page = 60,000/h が物理的な上限です。100万フォロワーのアカウントを全件取得するには約16時間。短縮する選択肢は (1) Pro/Enterprise tier の上位プランへ (cap が緩和される)、(2) TwitterAPI.io の followers/ids への移行 (15分 cap がない、5000 IDs/page、コストも約 1/33)、または (3) 取得対象を最新 N% のフォロワーに絞る、のいずれかです。
Tweet 投稿のレート制限は何ですか?
公式 X API の POST /2/tweets は user context で 200/15min + 100/24h の 2 重 cap。DELETE /2/tweets/:id は 50/15min。これらは burst を許さない設計で、bot/automation の濫用防止が目的です。書き込み系は本記事の主題ではなく、TwitterAPI.io も read-only サービスのため対応していません。書き込みは公式 X API を使う必要があります。
続けて読む
- X API Pricing — 公式 docs.x.com本記事の per-call 単価 ($0.005, $0.010, $0.001) と spending limits の仕様はこのページに準拠しています。
- X API Rate Limits — 公式 docs.x.com本記事の endpoint 別 15分 cap (user/app context 共通) はこのページに基づく抜粋です。
- About the X API — pay-per-usage モデルの概要Pay-per-use + no-monthly-cap + spending limits の3層構造はこのページに公式記載されています。
- X (Twitter) API 料金プラン完全ガイド — 従量課金の単価表
- Twitter (X) API でデータを取得する方法 — 3 つのアプローチ
- Twitter (X) API の使い方 — 5 分で始める
- Twitter rate-limit exceeded — EN 版の同テーマ詳細解説
- TwitterAPI.io 料金詳細 — per-call rates and volume tiers