Twitter API のエラー一覧｜Bad Authentication data と 403 の違い

編集

この記事の要点

Twitter（X）API のエラーは、まず HTTP ステータス（401 / 403 / 429 など）で大きく分類できる
401 系 = 認証の失敗（キーやトークンが違う・署名がずれている）。代表は「Bad Authentication data」
403 系 = 認可・権限の失敗（誰かは分かるが権限やプランが足りない）。代表は「Your credentials do not allow access to this resource」
429 = レート制限。レスポンスヘッダの x-rate-limit-reset の時刻まで待つ
切り分けは「認証情報 → アプリの権限・プロジェクト設定 → プラン・レート制限」の順に確認すると早い

Twitter（現 X）の API を使っていてエラーが返ってきたときに、どのページを見ればよいかを判断するためのページです。個別のエラーの詳しい対処は、下の表のリンク先で説明しています。

このカテゴリの記事

エラーメッセージ	原因のあたり
Bad Authentication data.	API キーやアクセストークンが不正・期限切れ・欠落している。OAuth 1.0a の署名計算がずれている場合もある
Your credentials do not allow access to this resource	403 Forbidden。認証は通っているが、そのリソースへの権限が無い。AWS PA-API / S3 / API Gateway でも同じ形で出る

この 2 つは似て見えますが、止まっている段階が違います。前者は「あなたが誰か分からない」という認証の失敗、後者は「あなたが誰かは分かるが、それを触る権限が無い」という認可の失敗です。

切り分けの手順としては、まず認証情報そのものを確認し、それが正しいと分かってから権限やプランの設定を疑う、という順序になります。逆にやると、正しいキーを何度も入れ直すことになって時間を失います。

エラーレスポンスの読み方

API v1.1 と v2 では、エラーの返し方が異なります。どちらの形式かを見れば、使っているエンドポイントの世代も分かります。

v1.1 形式: errors 配列とエラーコード

{"errors":[{"code":215,"message":"Bad Authentication data."}]}

数値の code で原因が特定できます。古いライブラリやサンプルコードは v1.1 を前提にしていることが多く、このコードで検索すると情報が見つかりやすくなります。

v2 形式: title / detail / type

{
  "title": "Unauthorized",
  "type": "about:blank",
  "status": 401,
  "detail": "Unauthorized"
}

v2 では HTTP ステータスと title・detail を見ます。権限不足などの場合は reason に「client-not-enrolled」のような理由が入ることもあります。なお v2 では、検索結果の一部だけ取得に失敗した場合などに、HTTP 200 のまま errors 配列が付いて返ることがあるため、ステータスだけでなく本文も確認してください。

HTTP ステータス別の原因と対処

ステータス	意味	よくある原因	まず確認すること
400 Bad Request	リクエストの形式が不正	必須パラメータの欠落、不正な値、JSON の書式ミス	エンドポイントの仕様とパラメータ名
401 Unauthorized	認証の失敗	キー・トークンの誤り、再生成後の古いトークン、OAuth 1.0a 署名のずれ、PC の時刻ずれ	キーとトークンを Developer Portal の値と照合
403 Forbidden	認可の失敗	アプリの権限が Read のみ、アプリがプロジェクトに紐づいていない、プランで使えないエンドポイント、認証方式の不一致	アプリの権限設定・プロジェクト・プラン
404 Not Found	対象が存在しない	削除済みの投稿、存在しないユーザー、エンドポイント URL の誤り	ID と URL
429 Too Many Requests	レート制限超過	短時間に呼びすぎ、月間の上限到達	レスポンスヘッダの残り回数とリセット時刻
500 / 503	X 側の障害・過負荷	一時的なサーバー側の問題	時間をおいて再試行（指数バックオフ）

v1.1 の主なエラーコード

code	メッセージ（要旨）	意味
32	Could not authenticate you	認証できない。署名や時刻、キーの組み合わせの誤り
88	Rate limit exceeded	レート制限超過
89	Invalid or expired token	アクセストークンが無効または失効
187	Status is a duplicate	直前と同じ内容の投稿
215	Bad Authentication data	認証情報が欠けている・形式が不正
220	Your credentials do not allow access to this resource	認証は通ったがそのリソースへの権限がない
453	You currently have access to a subset of ... endpoints	契約中のアクセスレベルでは使えないエンドポイント

403 で特に多いパターン

投稿しようとしたらアプリ権限が Read のみ: Developer Portal のアプリ設定（User authentication settings）で Read and write に変更し、アクセストークンを再生成する。権限変更前に発行したトークンには新しい権限が反映されない
Bearer Token でユーザー操作をしようとした: 投稿やいいねなど「ユーザーとしての操作」は、アプリ単体の Bearer Token（OAuth 2.0 App-Only）では実行できない。OAuth 1.0a User Context か OAuth 2.0（PKCE）のユーザートークンを使う
アプリがプロジェクトに属していない: v2 エンドポイントは、Developer Portal でプロジェクトに紐づいたアプリのキーでないと 403（client-not-enrolled）になる
プランで使えないエンドポイント: 2023 年以降、無料で使える範囲は大きく制限されている。利用できるエンドポイントや上限は変更が多いため、2026 年時点の最新の条件は Developer Portal と公式ドキュメントで確認する

429（レート制限）の確認方法

レスポンスヘッダに残り回数とリセット時刻が入っています。

x-rate-limit-limit: 300
x-rate-limit-remaining: 0
x-rate-limit-reset: 1767225600

x-rate-limit-reset は UNIX 時間（秒）です。この時刻までリクエストを止め、再開時も一気に送らないようにします。ループで API を呼んでいる場合は、エラー時に待たずに再試行し続けて状況を悪化させていないかを確認してください。

切り分けの手順

エラーの HTTP ステータスとレスポンス本文（code / title / detail）を記録する
401 系なら、API Key・API Secret・Access Token・Access Token Secret（または Bearer Token）を Developer Portal の値と照合する。前後の空白や改行の混入、環境変数の読み込み漏れも疑う
OAuth 1.0a を自前で実装している場合は、PC やサーバーの時刻が大きくずれていないか確認する
403 系なら、アプリの権限・プロジェクトへの紐づけ・認証方式・プランを順に確認する
429 なら、リセット時刻まで待ち、呼び出し頻度を下げる
curl などの単純なリクエストで同じエラーが出るか試し、ライブラリ側の問題かどうかを切り分ける

ページ一覧

その他