メインコンテンツへスキップ
X API は標準的な HTTP ステータスコードを使用します。成功したリクエストは 2xx コードを返し、エラーの場合はレスポンスボディ内の詳細とともに 4xx または 5xx コードを返します。

​
HTTP ステータスコード

​
成功コード

Code意味説明
200OKリクエストが成功しました
201CreatedPOST リクエストでリソースが作成されました
204No Contentレスポンスボディのない成功レスポンスです (DELETE リクエスト)

​
Client エラーコード

CodeMeaningCommon causes
400不正なリクエスト (Bad Request)無効な JSON、不正なクエリ、必須パラメータの不足
401認証エラー (Unauthorized)無効または不足している認証情報
403Forbidden (権限なし)認証は有効だが、このリソースやアクションの権限がない
404Not Found (リソースが見つからない)リソースが存在しないか、削除されている
409競合 (Conflict)ストリームにルールが設定されていない (filtered stream のみ)
429リクエスト過多 (Too Many Requests)レート制限または利用上限を超過した

​
サーバーエラーコード

CodeMeaningWhat to do
500内部サーバーエラー少し待ってから再試行し、ステータスページ を確認してください
502不正なゲートウェイ少し待ってから再試行してください
503サービス利用不可X が過負荷です。少し待ってから再試行してください
504ゲートウェイタイムアウト少し待ってから再試行してください

​
エラーレスポンス形式

エラーレスポンスには構造化された詳細情報が含まれています。 
{
  "title": "Invalid Request",
  "detail": "The 'query' parameter is required.",
  "type": "https://api.x.com/2/problems/invalid-request"
}
Field説明
typeエラー種別を識別するURI
titleエラーの簡潔な説明
detailこのエラーに関する具体的な説明
エラーの種類に応じて、追加のフィールドが含まれる場合があります。

​
エラーの種類

Type説明
about:blank汎用エラー (HTTP ステータスコードを参照)
.../invalid-requestリクエストの形式不備または無効なパラメータ
.../resource-not-foundポスト、ユーザー、その他のリソースが存在しない
.../not-authorized-for-resource非公開／保護されたコンテンツへのアクセス権がない
.../client-forbiddenApp が登録されていない、または必要なアクセス権が付与されていない
.../usage-capped利用上限を超過
.../rate-limit-exceededレート制限を超過
.../streaming-connectionストリーム接続の問題
.../rule-capFiltered Stream のルールが多すぎる
.../invalid-rulesルール構文エラー
.../duplicate-rulesルールがすでに存在する

​
部分的なエラー

一部のリクエストは部分的に成功することがあります。200 のレスポンスには data と errors の両方が含まれる場合があります。 
{
  "data": [
    {"id": "123", "text": "Hello"}
  ],
  "errors": [
    {
      "resource_id": "456",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [456].",
      "type": "https://api.x.com/2/problems/resource-not-found"
    }
  ]
}
これは複数のリソースをリクエストし、その一部が利用できない場合に発生します。

​
一般的なエラーのトラブルシューティング

認証を確認する:
  • エンドポイントに対して正しい認証方式を使用していることを確認する
  • 認証情報が再生成されていないか確認する
  • Authorization ヘッダーの形式を確認する
  • OAuth 1.0a の場合は、署名計算が正しいことを確認する
認証ガイド →
アクセスを確認する:
  • App がこのエンドポイントへアクセスできることを確認する
  • 一部のエンドポイントは特定の登録や承認が必要
  • ユーザーコンテキストのエンドポイントには適切な OAuth スコープが必要
  • リソースが非公開または保護されている可能性がある
レート制限:
  • 再試行のタイミングは x-rate-limit-reset ヘッダーを確認する
  • 指数バックオフを実装する
  • レスポンスのキャッシュを検討する
  • リクエストを時間枠全体に分散させる
レート制限ガイド →
リクエストを修正する:
  • JSON 構文を検証する
  • 必須パラメータの欠落がないか確認する
  • パラメータの型 (文字列か数値か) を検証する
  • クエリ内の特殊文字をエスケープする
次の要因を確認する:
  • 保護されたアカウントの投稿は、認可がある場合にのみ表示される
  • 削除された投稿は 404 を返す
  • 一部の投稿は特定の地域で表示が制限されることがある
  • 検索クエリ構文が正しいことを確認する
再接続を処理する:
  • バックオフ付きの自動再接続を実装する
  • 欠落データの復旧機能を利用する
  • (クライアントの処理が追いつかないことによる) バッファフルによる切断を確認する
  • 少なくとも 1 つのストリームルールが存在することを確認する
ストリーミングガイド →

​
レート制限ヘッダー

すべてのレスポンスにレート制限情報が含まれます。 
x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800
HeaderDescription
x-rate-limit-limit現在のウィンドウでの最大リクエスト数
x-rate-limit-remaining残りのリクエスト数
x-rate-limit-resetウィンドウがリセットされる時刻 (Unix タイムスタンプ)

​
ベストプラクティス

ステータスコードを確認する

レスポンスボディを解析する前に、必ず HTTP ステータスコードを確認してください。

部分的なエラーを処理する

200 レスポンスであっても errors 配列が含まれていないかどうかを確認してください。

リトライロジックを実装する

429 および 5xx エラーには指数バックオフを使用してください。

リクエスト詳細をログに記録する

デバッグ用に request ID とタイムスタンプを含めてください。

​
ヘルプを利用する

エラーについて質問を投稿する際は、次の情報を含めてください。
  • API エンドポイント URL
  • リクエストヘッダー (認証情報は必ずマスクしてください)
  • エラー応答の全文
  • 想定していた挙動
  • 既に試した手順

Developer Forum

質問したり、解決策を検索したりできます。

API Status

既知の問題が発生していないか確認してください。