Twitter APIのエラーコードと対処法

#X APIエラーの読み方

公式X APIへの呼び出しが失敗すると、返ってくるのは3つです。HTTPステータス、JSON本文、そして多くのエンドポイントではレート制限ヘッダーです。ステータスは失敗の種類を、本文はその種類の中のどの原因に当たったかを、ヘッダーはレート制限がいつリセットされるかを教えてくれます。

X API v2の本文は共通の形で、title、detail、type を持ちます。typeは https://api.x.com/2/problems/ 配下のURIで、client-not-enrolled のような reason が付くこともあります。古いv1.1のエンドポイントや、Xのv2ドキュメントにあるレート制限のレスポンスは、代わりに番号付きの code と message を持つ errors 配列を使います。たとえば {"errors": [{"code": 88, "message": "Rate limit exceeded"}]} です。Xは人間向けの文言をいつでも書き換えられるため、コードは type、reason、code で分岐させてください。

200でもエラーが含まれることがあります。1回のリクエストで複数の投稿やユーザーを指定し、一部が削除済みや非公開だった場合、Xは見つかったものを data に入れ、残りを resource-not-found または not-authorized-for-resource というtypeで errors 配列に並べます。成功したレスポンスも含め、毎回 errors を確認してください。

例外を投げる前に、本文を出力してください。Pythonの raise_for_status() はステータス行しか表示しません。Xのスタッフ自身もフォーラムで response.text を出力するよう開発者に求めています。本文には、問題のあるパラメーターや設定が書かれているからです。

#X APIのステータスコードと対処法

公式X APIが返すエラーステータスは11種類あります。うち5つ（429、500、502、503、504）は待って再試行すれば解消し、残りの6つはリクエスト、キー、残高、アクセス権のいずれかを変えない限り何度でも失敗します。Xのレスポンスコードのリファレンス（新しいタブで開きます）には10種類が載っており、載っていないのは402です。

• 400 Bad Request

  公式X APIでの意味

  パラメーターの不足、形式の誤り、範囲外。本文の errors 配列が該当箇所を示す

  対処法

  本文が示すパラメーターを直す

  再試行

  しない

• 401 Unauthorized

  公式X APIでの意味

  Xが呼び出し元を確認できない。キーの誤りや失効、認証方式の誤り、OAuth 1.0a署名の不正

  対処法

  キーを再生成し、エンドポイントが指定する認証方式を使い、時計を同期する

  再試行

  しない

• 402 Payment Required

  公式X APIでの意味

  前払いの従量課金の残高が空。type は credits-depleted

  対処法

  クレジットを追加するか、資金のあるアプリのキーを使う

  再試行

  しない

• 403 Forbidden

  公式X APIでの意味

  キーは有効だが、このアプリ、トークン、アカウントには許可されていない

  対処法

  reason または code を読む。登録、権限、アクセスレベルのいずれか

  再試行

  しない

• 404 Not Found

  公式X APIでの意味

  投稿、ユーザー、URLが存在しない、または投稿が削除済み

  対処法

  IDとエンドポイントのパスを確認する

  再試行

  しない

• 409 Conflict

  公式X APIでの意味

  フィルタードストリームにルールがない

  対処法

  ルールを追加してから接続する

  再試行

  しない

• 429 Too Many Requests

  公式X APIでの意味

  レート制限の枠を使い切った（code 88）、または月間の利用上限に達した（usage-capped）

  対処法

  x-rate-limit-reset まで待つ。利用上限は次の請求サイクルまで待つ

  再試行

  リセット後

• 500 Internal Server Error

  公式X APIでの意味

  X内部の障害（code 131）

  対処法

  間隔を延ばしながら再試行する

  再試行

  する

• 502 Bad Gateway

  公式X APIでの意味

  Xのフロントサーバーが、背後のサービスから応答を得られなかった

  対処法

  間隔を延ばしながら再試行する

  再試行

  する

• 503 Service Unavailable

  公式X APIでの意味

  Xが容量超過（code 130）

  対処法

  間隔を延ばしながら再試行する

  再試行

  する

• 504 Gateway Timeout

  公式X APIでの意味

  Xのサーバーでリクエストがタイムアウトした

  対処法

  間隔を延ばして再試行し、1回あたりの取得量を減らす

  再試行

  する

#402 Payment Required：X APIのクレジット枯渇

公式X APIから402が返るのは、アプリに紐づく前払い残高が空になったときです。クレジットが入るまで、Xは課金対象の呼び出しをすべて拒否します。Xの従量課金モデルでは、読み取りのたびに前払いで課金され、Xの料金表（新しいタブで開きます）によると投稿は1件$0.005、ユーザーは1件$0.010です。2026年2月6日以降、新規の開発者に他の入り口はありません。

次は、ある開発者が2026年10月にXのフォーラムへ投稿した本文です。

{
  "title": "Payment Required",
  "detail": "credits depleted",
  "type": "https://api.x.com/2/problems/credits-depleted"
}

type のリンク先は役に立ちません。Xのエラーリファレンスに402の項目がないためで、この抜けは2026年7月に開発者がXのフォーラムで指摘（新しいタブで開きます）しています。原因は、多い順に次のとおりです。

• 残高がゼロ、またはわずかにマイナス。 リクエストの結果、ごくわずかなマイナスが残ることがあり、新しいクレジットで補われるまでXは呼び出しをブロックします。Developer Consoleでクレジットを購入してください。残高がゼロまたはマイナスの間、自動チャージは動きません。
• サイクルの支出上限に達した。 コンソールで設定した上限は、1回の請求サイクルでアカウントが使える最大額です。上限を引き上げるか、次のサイクルを待ちます。
• キーが別のアプリのもの。 Client ID、シークレット、Bearerトークンが別のProjectや古い開発者アカウントのアプリのものだと、コンソールには残高があっても課金対象の呼び出しはすべて失敗します。残高$20なのに402（新しいタブで開きます）になったある開発者の件も、2026年10月にまさにこの原因で決着しました。資金のあるアプリのキーをコピーして、認可をやり直してください。GET /2/users/me が通っても、確認できるのは認証が通ることだけです。
• バーストで残高が減る速度が、自動チャージの補充を上回る。 Xの料金ページは、チャージ分を5分以内に使い切れる利用量では、それでもクレジットが尽きることがあると注意しています。チャージ額を増やしてください。

知っておきたいこと

402と、typeが usage-capped の429は、どちらも有料の読み取りを止めますが、理由が異なります。402はお金の問題で、クレジットを追加すれば次の呼び出しから動きます。利用上限は量の問題です。従量課金は1請求サイクルあたり投稿の読み取り300万件で止まり、それを超えると、読み取りを再開できるのは次のサイクルか、月約$42,000からのEnterprise契約だけです。

#403 Forbidden、453、その他のアクセスエラー

403は、Xがキーを受け付けたうえでその操作を拒否したことを意味します。本文の reason または番号付きの code が、どの関門が閉じているかを示します。再試行しても開きません。特によく出会う6つは次のとおりです。

• client-not-enrolled（type は client-forbidden）：キーが、Projectに紐づいていないアプリ、またはエンドポイントが必要とするアクセスに登録されていないアプリのものです。Xのスタッフが2026年10月のスレッド（新しいタブで開きます）で案内したとおり、Developer Consoleでアプリを従量課金のProjectに入れ、そのアプリのキーを使ってください。
• 453：「You currently have access to a subset of X API v2 endpoints and limited v1.1 endpoints (e.g. media post, oauth) only.」（X API v2の一部のエンドポイントと、限られたv1.1エンドポイント（メディア投稿、OAuthなど）にしかアクセスできません）。呼び出しがメディアアップロードとOAuth以外のv1.1エンドポイントに送られており、tweepy.API などの古いクライアントがこの動作をします。代わりにv2のエンドポイントを呼びます。Pythonなら tweepy.Client、Node.jsなら twitter-api-v2 パッケージです。
• 261「Your App cannot perform write actions」（アプリは書き込みを実行できません）：アプリが読み取り専用に設定されています。読み取りと書き込みに切り替え、アクセストークンを再生成してください。古いトークンは、作成時の権限のままだからです。
• 保護されたアカウントや凍結されたアカウント：保護された投稿ではcode 179またはtype not-authorized-for-resource、凍結されたユーザーではcode 63です。こちら側でできることはないので、その項目はスキップします。
• 326、一時的なロック：トークンに紐づくアカウントがXのスパム検査に引っかかっています。x.comにログインして、Xが表示する確認を完了してください。
• 書き込み時の226と187：Xのスパムフィルターか、重複投稿です。226のメッセージの対処法は、Xが「自動化されたリクエスト」と判定する理由のガイドで個別に解説しています。

いいね、フォロー、引用投稿も2026年4月20日にセルフサービスのアクセスから外れたため、従量課金のアプリではこれらの書き込みは403で終わります。403の全メッセージとコンソールでの手順は、X API 403 Forbiddenのガイドにまとめています。

#429と5xx：待てば解消するエラー

429と5xxは、再試行で直せる唯一の種類のX APIエラーです。ただし適切なタイミングに限ります。429はリセット時刻、5xxは少しずつ延ばした間隔です。

code 88の429は、1つのエンドポイントの枠が残っていないことを意味します。すべてのレスポンスにある3つのヘッダー、x-rate-limit-limit、x-rate-limit-remaining、x-rate-limit-reset（秒単位のUnix時間）で現在位置を確認できます。ほとんどの枠は15分間です。typeが usage-capped の429は月間300万投稿の読み取り上限で、リセットヘッダーでは解除されません。Xアプリ上とAPIで各制限がどれだけ続くかは、Twitterのレート制限超過のガイドで解説しています。

5xxはX側の障害です。500とcode 131は内部エラー、503とcode 130は容量超過、502と504はXのサーバー間のタイムアウトを意味します。再試行の間隔は1、2、4、8秒と空け、それでもだめなら中止して本文をログに残します。

次のハンドラーは、成功の見込みがあるものだけを再試行し、それ以外では本文をメッセージに入れて停止します。

import time
import requests

RETRY = {500, 502, 503, 504}

def call_x(url, headers, params=None, tries=5):
    for attempt in range(tries):
        r = requests.get(url, headers=headers, params=params, timeout=30)
        if r.ok:
            body = r.json()
            for err in body.get("errors", []):  # partial errors in a 200
                print("skipped:", err.get("detail"))
            return body
        if r.status_code == 429 and "usage-capped" not in r.text:
            reset = int(r.headers.get("x-rate-limit-reset", time.time() + 60))
            time.sleep(max(reset - time.time(), 1) + 1)
        elif r.status_code in RETRY:
            time.sleep(2 ** attempt)
        else:  # 400-409 and a capped 429: fix the cause first
            raise RuntimeError(f"X API {r.status_code}: {r.text}")
    raise RuntimeError(f"X API still failing after {tries} tries")

#番号別のX APIエラーコード

番号付きのコードはv1.1 APIに由来し、現在も届きます。v1.1のレスポンス、Tweepyのトレースバック、code 88のようにレート制限された呼び出しのv2本文の一部などです。以下のメッセージとステータスは、Xが最後に公開したコード表（2023年5月にアーカイブ（新しいタブで開きます））のとおりです。453はXのフォーラムにある開発者の報告に基づきます。ここにないコードは、上のステータス表の該当ステータスに従ってください。

• 32

  Xのメッセージ

  Could not authenticate you.

  ステータス

  401

  原因と対処法

  キー、トークン、OAuth署名の誤り。再生成して署名し直す

• 34

  Xのメッセージ

  Sorry, that page does not exist.

  ステータス

  404

  原因と対処法

  エンドポイントのURLまたはIDの誤り

• 50

  Xのメッセージ

  User not found.

  ステータス

  404

  原因と対処法

  アカウントの削除または名前変更。ユーザーIDで検索する

• 63

  Xのメッセージ

  User has been suspended.

  ステータス

  403

  原因と対処法

  問い合わせ先のアカウントが凍結中。スキップする

• 64

  Xのメッセージ

  Your account is suspended and is not permitted to access this feature.

  ステータス

  403

  原因と対処法

  トークン自身のアカウントが凍結中。Xに異議申し立てをする

• 87

  Xのメッセージ

  Client is not permitted to perform this action.

  ステータス

  403

  原因と対処法

  このアプリにはエンドポイントが開放されていない

• 88

  Xのメッセージ

  Rate limit exceeded.

  ステータス

  429

  原因と対処法

  x-rate-limit-reset まで待つ

• 89

  Xのメッセージ

  Invalid or expired token.

  ステータス

  401または403

  原因と対処法

  トークンの失効または期限切れ。認可をやり直し、新しいトークンを保存する

• 92

  Xのメッセージ

  SSL is required.

  ステータス

  403

  原因と対処法

  TLS 1.2のHTTPSで呼び出す

• 99

  Xのメッセージ

  Unable to verify your credentials.

  ステータス

  403

  原因と対処法

  コンシューマーシークレットまたはトークンシークレットの誤り

• 130

  Xのメッセージ

  Over capacity.

  ステータス

  503

  原因と対処法

  間隔を延ばしながら再試行する

• 131

  Xのメッセージ

  Internal error.

  ステータス

  500

  原因と対処法

  間隔を延ばしながら再試行する

• 135

  Xのメッセージ

  Could not authenticate you.

  ステータス

  401

  原因と対処法

  時計のずれでOAuthタイムスタンプが不正。時計を同期する

• 144

  Xのメッセージ

  No status found with that ID.

  ステータス

  404

  原因と対処法

  投稿が削除済み、またはIDの誤り

• 179

  Xのメッセージ

  Sorry, you are not authorized to see this status.

  ステータス

  403

  原因と対処法

  投稿者が投稿を保護している

• 185

  Xのメッセージ

  User is over daily status update limit.

  ステータス

  403

  原因と対処法

  アカウントの投稿上限に達した。数時間待つ

• 186

  Xのメッセージ

  Tweet needs to be a bit shorter.

  ステータス

  403

  原因と対処法

  テキストが長さの上限を超えている

• 187

  Xのメッセージ

  Status is a duplicate.

  ステータス

  403

  原因と対処法

  同じテキストが投稿済み。内容を変える

• 215

  Xのメッセージ

  Bad authentication data.

  ステータス

  400

  原因と対処法

  Authorizationヘッダーがない、または形式が不正

• 220

  Xのメッセージ

  Your credentials do not allow access to this resource.

  ステータス

  403

  原因と対処法

  トークンが制限されている。必要なスコープを持つものを使う

• 226

  Xのメッセージ

  This request looks like it might be automated.

  ステータス

  403

  原因と対処法

  Xのスパムフィルターが書き込みを停止。頻度を落とす

• 261

  Xのメッセージ

  Your App cannot perform write actions.

  ステータス

  403

  原因と対処法

  読み取り専用のアプリ。読み取りと書き込みに設定し、トークンを再生成する

• 326

  Xのメッセージ

  ...this account is temporarily locked.

  ステータス

  403

  原因と対処法

  x.comにログインしてロックを解除する

• 327

  Xのメッセージ

  You have already retweeted this Tweet.

  ステータス

  403

  原因と対処法

  実行済み。成功として扱う

• 349

  Xのメッセージ

  You cannot send messages to this user.

  ステータス

  403

  原因と対処法

  受信者があなたのメッセージを受け付けていない

• 415

  Xのメッセージ

  Callback URL not approved for this client App.

  ステータス

  403

  原因と対処法

  アプリの設定に正確なコールバックURLを追加する

• 453

  Xのメッセージ

  You currently have access to a subset of X API v2 endpoints...

  ステータス

  403

  原因と対処法

  v1.1の呼び出し、またはアクセスレベルの不足。v2のエンドポイントを呼ぶ

#X API v2のproblem type

v2のレスポンスでは、type フィールドが原因を示します。Xが文書化している11種類に加え、文書化されていない credits-depleted があります。URIはすべて https://api.x.com/2/problems/ で始まります。

• invalid-request

  意味

  400。パラメーターが誤っており、errors に列挙される

  対処法

  そのパラメーターを直す

• resource-not-found

  意味

  投稿またはユーザーが存在しない。200の中に出ることも多い

  対処法

  スキップするか、IDを確認する

• not-authorized-for-resource

  意味

  保護または非公開のコンテンツ

  対処法

  スキップする

• client-forbidden

  意味

  reason 付きの403。多くは client-not-enrolled

  対処法

  アプリをProjectに移す

• credits-depleted

  意味

  402。前払い残高が空

  対処法

  クレジットを追加する

• usage-capped

  意味

  429。月間の利用上限

  対処法

  次の請求サイクルを待つ

• rate-limit-exceeded

  意味

  429。レート制限の枠

  対処法

  x-rate-limit-reset まで待つ

• streaming-connection

  意味

  ストリーム接続の問題

  対処法

  間隔を延ばしながら再接続する

• rule-cap、invalid-rules、duplicate-rules

  意味

  フィルタードストリームのルール：多すぎる、構文の誤り、既存

  対処法

  ルールを削除、修正、またはスキップする

• about:blank

  意味

  汎用エラー

  対処法

  ステータスを読む

400の errors 配列には、Xが拒否した値が正確に書かれています。次はXのフォーラムにある2026年10月の事例で、全アーカイブ検索がリクエスト時刻そのものの end_time を拒否したものです。

{
  "title": "Invalid Request",
  "detail": "One or more parameters to your request was invalid.",
  "type": "https://api.x.com/2/problems/invalid-request",
  "errors": [
    {
      "message": "Invalid 'end_time':'2026-10-20T08:04Z'. 'end_time' must be a minimum of 10 seconds prior to the request time.",
      "parameters": { "end_time": ["2026-10-20T08:04Z"] }
    }
  ]
}

Xスタッフの案内は、end_time をリクエスト時刻の10秒以上前に設定するか、省略することでした。

#APIキー1つで公開Xデータを読む：Sorsa API

失敗している呼び出しが公開データの読み取りだけなら、Twitter（X）API兼スクレイピングツールであるSorsa APIで、このページの話題のほとんどが不要になります。必要なのは ApiKey ヘッダーに入れるAPIキー1つだけで、Xの開発者アカウント、アプリ、Project、OAuthは要りません。そのため401の署名エラー、client-not-enrolled、453、402は発生しません。ご自身のXアカウントも一切使いません。

Sorsa APIは、すべてのエラーを {"message": "..."} という1つの本文の形で返します。出会うステータスは次のとおりです。

• 400

  Sorsa APIでの意味

  パラメーターの不足または形式の誤り

  対処法

  パラメーターを直す

• 401

  Sorsa APIでの意味

  invalid api key

  対処法

  ダッシュボードからキーをコピーし直す

• 403

  Sorsa APIでの意味

  missing key in request header、またはキーのリクエストを使い切った

  対処法

  ApiKey ヘッダーを送る。チャージまたはアップグレードする

• 404

  Sorsa APIでの意味

  投稿またはアカウントが存在しない、または非公開

  対処法

  IDを確認する

• 429

  Sorsa APIでの意味

  1秒間に20リクエストを超えた

  対処法

  1秒待つ

• 500

  Sorsa APIでの意味

  Sorsa側の障害

  対処法

  1〜2秒後に再試行する

2026年11月2日に、キーのエラーを実際のAPIに送って確認しました。ヘッダーを ApiKey ではなく Api-Key と綴ると、キーがまったくないものとして扱われ、403が返ります。

curl "https://api.sorsa.io/v3/info?username=error_codes_demo_acct" \
  -H "Api-Key: YOUR_API_KEY"

{"message": "missing key in request header"}

ヘッダーが正しく、キーが誤っている場合は、同じ呼び出しで 401 と {"message": "invalid api key"} が返ります。失敗したリクエストに課金されることはありません。各ステータスと原因は、ドキュメントのSorsa APIエラーコード（新しいタブで開きます）のページに載っています。

1. キーを取得する。 登録して、ダッシュボードからAPIキーをコピーします。最初の100リクエストは無料です。

2. 1リクエストで最大100投稿を読み取る。 POST /tweet-info-bulk（新しいタブで開きます） は投稿のリンクまたはIDを受け取り、各投稿を投稿者の完全なプロフィール付きで返します。

   curl -X POST "https://api.sorsa.io/v3/tweet-info-bulk" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tweet_links": ["2117203385470271488", "2117199027635167232"]}'
   

   {
     "tweets": [
       {
         "id": "2117203385470271488",
         "full_text": "Two layers in every error: status, then cause.",
         "created_at": "2026-11-02T09:12:44Z",
         "lang": "en",
         "likes_count": 41,
         "retweet_count": 6,
         "reply_count": 3,
         "view_count": 5210,
         "user": {
           "id": "1592041833471827968",
           "username": "error_codes_demo_acct",
           "display_name": "Error Codes Demo",
           "followers_count": 1840
         }
       },
       {
         "id": "2117199027635167232",
         "full_text": "Retry 429 and 5xx. Fix everything else first.",
         "created_at": "2026-11-02T08:55:20Z",
         "lang": "en",
         "likes_count": 27,
         "retweet_count": 4,
         "reply_count": 2,
         "view_count": 3380,
         "user": {
           "id": "1592041833471827968",
           "username": "error_codes_demo_acct",
           "display_name": "Error Codes Demo",
           "followers_count": 1840
         }
       }
     ]
   }
   

   レスポンス全体を表示

3. プロフィールも同じ方法で調べる。 GET /info（新しいタブで開きます） は username、user_id、user_link のいずれかで1件のプロフィールを返します。404は、アカウントが存在しないか非公開であることを意味します。

4. 残高を確認する。 GET /key-usage-info（新しいタブで開きます） は残りのリクエスト数と更新日を返し、この確認自体は無料です。429は1秒後に再試行し、有効なキーでの403は、チャージが必要なサインとして扱ってください。

IDによる投稿の読み取りは、Sorsa APIでは1リクエストあたり100投稿、1,000件あたり$0.014からです。公式X APIは1,000件あたり$5.00で、従量課金プランは月間300万件の投稿読み取りで止まります。

2026年11月22日から、公式X APIは各投稿に付いて返る投稿者プロフィールにも、1ユーザー$0.010で課金します（Xの通知（新しいタブで開きます））。Sorsa APIでは、すべての投稿が同じリクエストで投稿者の完全なプロフィールを含みます。Sorsa APIは読み取り専用です。投稿、いいね、メッセージ送信には、引き続き公式X APIを使ってください。

#目の前のエラーを直してから、読み取りを移す

X APIのほぼすべてのエラーは、2通りのどちらかで解決します。429と5xxは待つこと、それ以外はリクエスト、キー、残高、アプリのアクセス権を変えることです。エラーの原因が公開の投稿、プロフィール、フォロワーの読み取りなら、その読み取りをSorsa APIに移してください。APIキー1つ、分かりやすいエラーメッセージ、全プラン毎秒20リクエスト、投稿は1,000件あたり$0.014から。今すぐ100回分の無料リクエストで試せます。

#よくある質問