WEIR
API キーを取得
言語English中文
テーマ

X API 402 エラーの原因と対処：クレジット不足 2026

X API の 402 Payment Required は、従量課金のクレジット不足が原因です。再試行で直らない理由、残高の確認方法、自動チャージの落とし穴、Tweepy での止め方まで。


公開 · 更新 · 約 7 分で読めます · Read in English · 阅读中文版

カバー画像：X の呼び出しが止まった理由

X API の 402 エラー（Payment Required）は、従量課金のクレジットが不足し、X がリクエストを止めている状態です。

bot やスクリプトが急に止まった開発者向けです。原因、Developer Console での直し方、再試行せずに止まるコードをまとめました。

まず、X の API リファレンスにあるエンドポイントで残高を確かめます。

curl "https://api.x.com/2/usage/credits" \
  -H "Authorization: Bearer $BEARER_TOKEN"

total_balance が 0 なら、それが 402 の原因です。

402Payment Required：クレジット不足
$0自動チャージが止まる残高
3 か月X の無料クレジットの期限
$0.005ポスト 1 件の読み取り（2026 年 10 月）

X API の 402 エラーとは

X API は従量課金です。クレジットを買い、ポストやプロフィールを読むたびに差し引かれます。X の利用と請求のページは、残高がなくなると「クレジットを購入するまで API リクエストは失敗します」と書いています。

不思議なのは、X が 402 そのものを文書にしていないことです。10 月 26 日に確認したエラーコードのページには、400、401、403、404、409、429 と 5xx しかありません。

そこで、開発者が実際に見ている内容を確かめました。10 月 21 日に Weir で X を検索すると、18 日にもこのエラーを投稿した開発者がいました。ログでは、title が「Payment Required」、detail が「credits depleted」です。

X API のクレジット不足はなぜ起きる？

原因はたいてい次の 5 つです。どれも 10 月 26 日時点の X のドキュメントにあります。

  • 残高が 0 になった：ポスト 1 件で $0.005 なので、忙しいループはすぐ使い切ります。
  • 残高がマイナスになった：料金ページによると少しマイナスになることがあり、埋めるまで止まります。
  • 無料クレジットが失効した：特典のクレジットは付与から 3 か月で消えます。
  • 自動チャージが追いつかない：自動チャージは 5 分に 1 回までなので、速い処理に負けます。
  • 自動チャージが止まっていた：残高が 0 以下のあいだは動きません。

無料クレジットでつまずく人は多いです。X の無料クレジットのページでは、最初にクレジットを買うと $20、最初の自動チャージに $50 までの同額が付きます。

10 月 13 日からは、カードを登録するだけでは $20 は付きません。しかも無料クレジットは、買ったクレジットより先に使われます。3 か月それで動いていた bot は、失効した日に止まります。

GET /2/usage/credits の応答には free_grants があり、無料クレジットごとの expires_at で失効日を確かめられます。

Developer Console でクレジット不足を直す

直すには、console.x.com の X Developer Console で人がクレジットを買います。

  1. 残高を確認GET /2/usage/credits か、コンソールの Billing → Credits。
  2. クレジットを購入カードがなければ Billing information で登録して購入。
  3. 自動チャージを設定Recharge amount と Trigger threshold を選びます。
  4. 利用上限を設定1 回の請求期間で使う最大額を決めます。
  5. 処理を再開手で 1 回動かし、最初の応答を確かめます。

X の料金ページは、残高 0 のあと自動チャージは自分では再開しないとしています。手動で追加すると、自動チャージも戻ります。

利用上限にも注意点があります。上限に達すると、次の請求期間までリクエストが止まります。そのときのステータスコードを X は書いていないので、残高があるのに止まるなら上限も確かめます。

詳しい手順は X API キーの取得方法 のステップ 3 にもあります。

402 エラーを再試行しても直らない理由

402 はタイムアウトではありません。誰かが支払うまで、X の側では何も変わりません。

その点で、429 のレート制限（英語）とは正反対です。レート制限は時間が来れば解除されるので、待てば通ります。空の残高はひとりでに増えないので、再試行のループは終わりません。

失敗した呼び出しの料金はかかりません。X の利用と請求のページは、データを返した成功の応答だけが課金されるとしています。それでも処理は止まったままで、ログが埋まっていきます。

Tweepy で 402 Payment Required を捕まえて止める

Tweepy には 402 専用の例外クラスがありません。ソースでは 400、401、403、404、429、5xx に名前付きの例外があり、それ以外は基底の tweepy.HTTPException になります。

メッセージは「402 Payment Required」と X の detail です。捕まえて終了します。

import os, sys, tweepy

client = tweepy.Client(bearer_token=os.environ["X_BEARER_TOKEN"])
try:
    response = client.search_recent_tweets(query="python", max_results=10)
except tweepy.HTTPException as error:
    if error.response.status_code == 402:
        sys.exit("X API のクレジット切れです。Developer Console で追加してください。")
    raise

wait_on_rate_limit=True には頼れません。Tweepy のコードは、これを 429 にしか使いません。

クレジットを使い切らないための 3 つの習慣

夜のあいだに残高を空にしないための習慣です。

  • 大きな処理の前に残高を見る：total_balance を読み、自分で決めた下限より少なければ止めます。
  • ページ数に上限を付ける：どのループにも最大ページ数を付け、「終わるまで」にしません。
  • 利用上限を設定する：自分のコードが間違えたときの最後の歯止めです。

ページ数の上限が大事な理由です。最近の検索は 1 回で最大 100 件を返し、1 件 $0.005 です。

上限のない検索ループの X API 費用
100 件 × 10 ページ$5
100 ページ$50
1,000 ページ$500

自分の処理は X API コスト計算ツール（英語）で試算できます。料金の全体は X API の料金 にまとめました。

Weir のクレジット不足はどう見える？

Weir は私たちが運営する、公開の X と Reddit のデータを読む API です。その点を踏まえて読んでください。Weir にも 402 があり、ルールは同じで、クレジット切れは再試行できません。

違いは、文書にしていることです。Weir の 402 は必ずコード quota_exceeded と "retryable": false を返します。パックを買うか、翌月の無料クレジットが入ると解除されます。

GET /v1/usage は無料で、クレジットが切れても応答します。

curl --url https://api.weirapp.io/v1/usage \
  --header "Authorization: Bearer $WEIR_API_KEY"

10 月 26 日に、私たちの調査用アカウントで同じ残高を MCP の get_usage から取得した data です。今月の無料枠は使い切り、追加分のクレジットが残っています。

{
  "balance": 8630,
  "available": 8630,
  "freeGrant": {
    "granted": 5000,
    "remaining": 0,
    "resetsAt": "2026-11-01T00:00:00.000Z"
  },
  "tier": "free",
  "spendingPaused": false
}

課金された応答にはすべて x-credits-remaining ヘッダーが付くので、0 になる前にスクリプトを止められます。無料枠は毎月 5,000 クレジットでカードは要らず、失敗した呼び出しは無料です。

Weir が向かないケース

  • 投稿、返信、DM：Weir は読み取り専用で、書き込みは X の API が必要です。
  • 自分のアカウントを読む：X の Owned Reads は 1 件 $0.001 で、なかなか勝てません。
  • X 自身との契約が必要：月 300 万ポストを超える Enterprise などです。
  • 1 ポストの単価だけが大事：TwitterAPI.io は 1,000 ツイート $0.15 で、小さなパックより安いです。

Weir は X の公認ではないので、使える範囲が変わることがあります。詳しくは Weir と公式 X API の比較（英語）にあります。

よくある質問

X API のエラー 402 は何を意味しますか？

従量課金の残高でリクエストをまかなえない、という意味です。Developer Console でクレジットを追加するまで止まります。X のドキュメントにこのコードは載っていませんが、エラーの detail には「credits depleted」とあります。

失敗したリクエストにも料金はかかりますか？

かかりません。X の利用と請求のページによると、課金されるのはデータを返した成功の応答だけです。402 は無料ですが何も返さないので、再試行のループはお金ではなく時間を無駄にします。

自動チャージをオンにしているのに 402 が出るのはなぜ？

理由は 2 つです。自動チャージは 5 分に 1 回までなので、急な処理が先に使い切ることがあります。また、残高が 0 以下のあいだは止まります。その場合は手動で追加すると再開します。

X API の無料クレジットに期限はありますか？

あります。特典のクレジットは付与から 3 か月で失効し、買ったクレジットより先に使われます。2026 年 10 月時点の無料クレジットのページによると、買ったクレジットは対象外です。

参考資料

X の資料は 2026 年 10 月 26 日に確認しました。

あわせて読みたい