Twitter API エラーコードと HTTP ステータスのリファレンス

TwexAPI の Twitter/X API エラーを解決：HTTP 401、403、429、5xx、無効な auth_token、重複ツイート、DM 制限、安全な再試行。

TwexAPI は Twitter/X API の失敗を HTTP ステータスコードと、取得できる場合は上流の X エラーコードで通知します。401 では認証情報の修正、403 ではアクセス権やアカウントの問題の解消、429 ではレート制限が解除されるまでの待機が必要です。再試行する前にレスポンス本文を確認してください。

このリファレンスでは、Twitter API エラーコード、invalid auth_token、重複ツイート、DM 制限への対処方法を説明します。エンドポイントのパスは現在の API リファレンス に準拠しています。MCP エラー、ページネーションの復旧、SDK の例については、エラー処理 を参照してください。

以下のメッセージと上流のコードは、トラブルシューティングの例です。レスポンスの構造や HTTP ステータスへの対応付けはエンドポイントによって異なる場合があります。エンドポイントのスキーマと実際のレスポンスを併せて確認してください。

Twitter API エラーの対処方法を見つける

• HTTP 401 / Invalid auth_token：TwexAPI の API キーと、書き込みエンドポイントに使用する X セッションの認証情報の両方を確認してください。認証 を参照してください。
• HTTP 403：メッセージを確認し、クレジット不足、非公開投稿、アカウント制限、Premium 要件のどれに該当するか判断してください。同じリクエストを繰り返してもアクセス権は復旧しません。
• HTTP 429 / Too Many Requests：Retry-After または retry_after に従い、リクエストの頻度制限と X アカウントの 1 日の上限を区別してください。レート制限 を参照してください。
• HTTP 500 / 502 / 503：一時的な読み取りの失敗は、待機時間に上限を設けたバックオフで再試行してください。書き込みを繰り返す前に、すでに成功していないか確認してください。
• X コード 187、344、502：これらは上流の X コードであり、HTTP ステータスコードとは別のものです。Twitter/X コード表 と 再試行に関する質問 を確認してください。

エラーレスポンスの形式

HTTP ステータスと JSON 本文全体を保存してください。TwexAPI のレスポンスには code と msg が含まれる場合があり、リクエストの検証エラーでは detail が使用されます。

{
  "code": 500,
  "msg": "Internal server error"
}

{
  "detail": [
    {
      "loc": ["body", "cookie"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

レスポンスに上流からの追加メタデータが含まれる場合は、それも保存してください。

• error：提供される場合はエラーメッセージを示します。すべてのエンドポイントがこのフィールドを使用するとは限りません。
• twitter_error_code：提供される場合は X エラーコードを示します。HTTP ステータスとは別のもので、たとえば X コード 502 は DM 制限を指します。
• retry_after：提供される場合は待機する秒数を示します。HTTP の Retry-After ヘッダーにも従ってください。

省略可能なフィールドの存在を必須としたり、メッセージの完全一致だけで処理を分岐したりしないでください。本文に別の code が含まれていても、HTTP ステータスが 2xx 以外なら失敗です。

よくあるエラー（すべてのエンドポイント）

どのリクエストでも、以下の条件を確認してください。実際のメッセージは異なる場合があります。

Twitter API の HTTP ステータスコード

Twitter/X API エラーコード

レスポンスに上流の X コードが含まれる場合は、以下の意味を参照してください。これらは X コードであり、HTTP ステータスではありません。また、すべてのエンドポイントが twitter_error_code を公開するわけではありません。

ツイートの読み取りと検索

POST /twitter/{screen_name}/timeline/page、/twitter/tweets-replies/page、/twitter/advanced_search/page に適用されます。

投稿とエンゲージメント

ツイートの作成

POST /twitter/tweets/create

tweet_content、任意の reply_tweet_id、および cookie に X の認証情報を指定してください。ツイートまたは返信の作成 を参照してください。

いいね・リツイート・ブックマーク

POST /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

DELETE /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

ツイートの削除

POST /twitter/tweets/delete-batch

1 件のツイートを削除するには target_id を指定してください。省略すると一括削除になります。エラーから復旧する際は、元のリクエストのフィールドを保持してください。

フォロー・フォロー解除

POST /twitter/user/follow · DELETE /twitter/user/follow

プロフィール・アバター・バナーの更新

POST /twitter/profile

画像 URL には profile_image と profile_banner、X の認証情報には cookie を使用してください。

メディアの添付

ツイートの作成時や DM の送信時にメディアを添付します。現在のリファレンスには独立したメディアアップロード用ルートはありません。ツイート作成時の media_urls は、最大 4 枚の画像、1 件の GIF、または 1 件の動画に対応しています。GIF・動画を他のメディアと混在させないでください。アクセスできない URL、非対応の形式、拒否されたファイルサイズを修正してから再試行してください。フィールド名と制約はエンドポイントのスキーマに従ってください。

ダイレクトメッセージ

POST /v3/twitter/send-dm · /v3/twitter/dm-history · /v3/twitter/conversations

権限の確認には POST /v2/dm/status を使用してください。DM の送信 を参照してください。

データの読み取り

POST /v2/tweet/detail · /twitter/tweets/lookup · /twitter/users/by_ids · /v3/twitter/users/followers · /v3/twitter/users/following · /twitter/tweets/thread_by_id · /twitter/tweets/{tweet_id}/replies/page

GET /twitter/{screen_name}/about · /twitter/search-user/{keyword}/{target_count}

記事

POST /x/article · GET /x/article/{tweet_id}/markdown

書き込み：POST /x/articles/draft · PUT /x/articles/{article_id}/cover · /x/articles/{article_id}/title · /x/articles/{article_id}/content · POST /x/articles/{article_id}/publish または /x/articles/publish。

以下の Premium 要件は記事の公開に適用されます。article_id を保持し、失敗したステップだけを再試行できるよう、段階的な記事作成フロー の使用を推奨します。

再試行ガイド

ヒント： 429 と一時的な 5xx には、ジッターを加え、待機時間に上限を設けたバックオフを使用してください。400/401/403/404/409/422 では、先に入力、認証情報、またはアカウントのアクセス権を修正してください。

Twitter API エラーと再試行に関する質問

Twitter API が 401 または invalid auth_token を返すのはなぜですか？

HTTP 401 は、TwexAPI の API キーが未指定または無効であることを意味する場合があります。書き込みエンドポイントでは、Invalid auth_token または X コード 32 は X セッションの期限切れを意味する場合もあります。再試行前に Bearer ヘッダーを修正するか、cookie に指定した X の認証情報を更新してください。

Twitter API エラー 403 と 429 の違いは何ですか？

HTTP 403 は、クレジット不足、非公開コンテンツ、制限されたアカウント、Premium 専用の操作など、アクセス上の問題を示します。HTTP 429 はリクエストまたはアカウントの上限を示します。403 では原因を解消し、429 では示された上限がリセットされるまで待ってください。

Twitter API の 429 Too Many Requests を解決するにはどうすればよいですか？

Retry-After または retry_after が提供されている場合はその時間だけ待ち、同時実行数を減らして、待機時間に上限を設けたバックオフで再開してください。1 日のツイート・DM 上限では、短い待機だけではなく、上限がリセットされるまで待つ必要があります。読み取りを再試行する際は、失敗したページのカーソルを保持してください。

Twitter エラーコード 187 は何を意味しますか？

X エラーコード 187 はツイート本文の重複を意味します。前の書き込みですでに投稿が作成されていないか確認してください。別の投稿を公開するつもりなら、同じリクエストを繰り返さずに tweet_content を変更してください。

Twitter エラーコード 344 は何を意味しますか？

X エラーコード 344 は、ネットワークまたは IP に関連した一時的な投稿制限を示します。バックオフし、指定したプロキシを確認し、書き込みを再試行する前にアカウントのタイムラインを確認してください。これは X エラーコードであり、HTTP ステータスコードではありません。

Twitter API エラー 500、502、503 は再試行すべきですか？

一時的な読み取りの失敗は、ジッターを加え、待機時間に上限を設けたバックオフで再試行してください。書き込みがタイムアウトしたり 5xx を返したりした場合は、まずタイムライン、DM 履歴、またはエンゲージメントの状態を確認してください。失敗レスポンスは、書き込みが適用されなかったことを証明するものではありません。

TwexAPI の 422 検証エラーは再試行すべきですか？

同じ入力のまま再試行しないでください。TwexAPI はリクエストの検証エラーに HTTP 422 を使用します。detail で失敗したフィールド、場所、種類を確認し、エンドポイントのスキーマに従ってリクエストを修正してください。

Twitter エラーコード 502 は HTTP 502 と同じですか？

いいえ。X エラーコード 502 は 1 日の DM リクエスト上限を指し、HTTP 429 とともに返される場合があります。HTTP 502 は上流のレスポンス障害を示します。再試行方針を決める前に、HTTP ステータスと、提供されている場合は twitter_error_code の両方を確認してください。

関連ページ

• エラー処理 — MCP、SDK、ページネーションの復旧
• 認証 — API キーと X セッションの認証情報
• レート制限 — バックオフとスループット
• API 概要 — 現在のエンドポイントリファレンス