---
title: "Twitter API エラーコードと HTTP ステータスのリファレンス"
description: "TwexAPI の Twitter/X API エラーを解決：HTTP 401、403、429、5xx、無効な auth_token、重複ツイート、DM 制限、安全な再試行。"
lastModified: "2026-10-08"
sidebar:
  label: "エラーリファレンス"
seo:
  title: "Twitter API エラーコード：401、403、429 と再試行"
search:
  tags: ["Twitter API エラーコード", "X API エラー", "無効な auth_token", "429 Too Many Requests", "twitter_error_code"]
---

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

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

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

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

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

## エラーレスポンスの形式

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

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

```json
{
  "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` 以外なら失敗です。

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

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

| ステータス | メッセージ | 意味 | 対処方法 |
| --- | --- | --- | --- |
| **401** | `Invalid or missing API key` | API キーが未指定または不正 | `Authorization: Bearer <key>` ヘッダーを確認する |
| **400** | `Missing required … param: <x>` | 必須フィールドやパラメータが未指定または無効 | リクエストを修正する |
| **429** | `Please try again shortly.`（当サービスの処理能力）· `Rate limit exceeded…` · または X 側の制限メッセージ | リクエスト過多、当サービスの処理能力、または **X アカウントの上限**（例：1 日の DM・ツイート上限。`twitter_error_code` が含まれる場合がある） | `retry_after` / `Retry-After` に従う。アカウントの 1 日の上限では、より長く待つ必要がある |
| **403** | クレジットを使い切った、またはアクセスが拒否された | クレジットまたはアカウント権限が不足 | 残高とアカウントのアクセス権を確認する |
| **422** | 検証エラー（`detail`） | リクエストのフィールドがスキーマ検証に失敗 | `detail` に示されたフィールドを修正する。同じ入力のまま再試行しない |
| **500** | `Internal server error` | 一時的なエラーが発生 | 少し待って再試行する |

:::warning
**401 には 2 種類あります。** API レベルの `401` は、**API キー**が不正であることを意味します。書き込みエンドポイント（投稿、いいね、プロフィール更新）では、`401` は **`cookie` に指定した X セッションの認証情報**が無効または期限切れであることを意味する場合もあります。メッセージには `Invalid auth_token` または `Could not authenticate you` と表示される場合があります。その場合は X セッションの認証情報を更新してください。[認証](/ja/authentication#オペレーション記述とbyocbring-your-own-cookie) を参照してください。
:::

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

| ステータス | 意味 |
| --- | --- |
| **200** | 成功 |
| **202** | 受け付け済み。このステータスを返すエンドポイントでは、操作の完了待ち |
| **400** | 不正なリクエスト、パラメータの未指定・無効、不正なプロキシ URL、またはメディアサイズ超過 |
| **401** | 未認証。API キーが不正、または `auth_token` が無効・期限切れ |
| **403** | アクセス禁止。クレジット不足、**対象アカウントが非公開または凍結されている**（投稿を読み取れない）、使用中のアカウントが凍結・ロックされている、権限の制限、または Premium 専用の操作 |
| **404** | 見つからない。ユーザー、ツイート、またはリソースが存在しない |
| **409** | 競合。重複ツイート |
| **410** | リソースを利用できない。本文でアカウント凍結の詳細を確認する |
| **422** | リクエストの検証に失敗。`detail` を確認して入力を修正する |
| **423** | X が返した場合：アカウントがロックされているか、認証が必要 |
| **429** | リクエスト過多。レート制限に到達 |
| **500 / 502 / 503** | サーバーまたは上流の一時的なエラー。再試行する |

## Twitter/X API エラーコード

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

| コード | 意味 | 対処方法 |
| --- | --- | --- |
| **32** | 認証できなかった | `cookie` に指定した X セッションの認証情報を更新する |
| **63** | 対象アカウントが凍結されている | アクセス可能なアカウントを使用するか、アクセスの復旧を待つ |
| **64** | 自分のアカウントが凍結されている | 別のアカウントを使用する |
| **131** | X 内部の一時的なエラー | 再試行する |
| **139** | すでにいいね済み | 現在の状態を確認する。操作を繰り返さない |
| **144** | 指定された ID のツイートが見つからない | ツイートが削除されているか、ID が不正 |
| **187** | 重複ツイート | 前の投稿を確認し、新しい投稿を意図している場合は本文を変更する |
| **226** | リクエストが自動化されたものと判断された | 再試行する |
| **326** | アカウントが一時的にロックされている | `x.com/account/access` でロックを解除してから再試行する |
| **327** | すでにリツイート済み | 現在の状態を確認する。操作を繰り返さない |
| **344** | 投稿が一時的に制限されている（アカウントではなくネットワーク・IP の制限） | バックオフし、プロキシを指定した場合は確認する。再試行前に書き込み結果を確認する |
| **349** | このユーザーにメッセージを送れない | 相手が自分からの DM を受け付けていない |
| **399** | X セッションのログインに失敗 | X セッションの認証情報を確認する |
| **433** | 返信が制限されている、または Premium が必要 | ツイートの返信対象が制限されているか、操作に X Premium が必要 |
| **465** | 古いツイートをリツイートできない | ツイートが古すぎるためリツイートできない |
| **476** | メッセージリクエストの送信が許可されていない | アカウントが DM リクエストを送信できない |
| **502** | 1 日の DM（メッセージリクエスト）上限に到達 | 24 時間待つか、上限の高い X Premium アカウントを使用する |

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

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

| ステータス | メッセージ | 対処方法 |
| --- | --- | --- |
| **403** | `This account's posts are not available. The account is protected (private), suspended, or no longer active.` | **同じリクエストを再試行しない**。成功するにはアクセス条件の変更が必要。承認されたフォロワー以外は対象の投稿を読めない。公開アカウントを対象にする。 |
| **403** | `This account is suspended, so its posts are not available.` | 対象アカウントが凍結されている。アクセス可能なアカウントを使用するか、アクセスの復旧を待つ。 |
| **502** | `Upstream returned an unexpected response — please retry.` | 上流の障害。**待機時間に上限を設けたバックオフで再試行する**。同じカーソルを保持する。 |

:::info
**対象アカウントが非公開・凍結されている**ことによる `403` では、アクセス権またはアカウントの変更が必要です。`502` は一時的な場合があります。再試行方針を決める前に、ステータスと本文を確認してください。
:::

## 投稿とエンゲージメント

### ツイートの作成

**POST** `/twitter/tweets/create`

`tweet_content`、任意の `reply_tweet_id`、および `cookie` に X の認証情報を指定してください。[ツイートまたは返信の作成](/ja/api-reference/tweet-actions-endpoints/create-tweet-twitter-tweets-create-post) を参照してください。

| ステータス | コード | メッセージ | 対処方法 |
| --- | --- | --- | --- |
| **409** | 187 | `Status is a duplicate.` | 投稿がすでに存在するか確認する。新しい投稿なら本文を変更する |
| **403** | 433 | `The original Tweet author restricted who can reply…` | そのツイートでは自分からの返信が許可されていない |
| **403** | 433 | 長文・長時間動画には Premium が必要 | Premium アカウントを使用するか、コンテンツを短くする |
| **403** | n/a | コミュニティのメンバーではない | 先にコミュニティに参加する |
| **429** | 344 | 投稿が一時的に制限されている（ネットワーク・IP の制限） | バックオフする。指定したプロキシを確認し、投稿が作成されたか確認する |
| **502** | n/a | `X returned an empty result`（結果未確認） | 再試行前にアカウントのタイムラインを読む。書き込み結果は未確認 |
| **400** | n/a | `File size exceeds…` | メディアファイルのサイズを小さくする |
| **503** | 226 | `This request looks automated` | バックオフし、再試行前に書き込み結果を確認する |
| **502 / 503** | n/a | 一時的な接続エラー | 再試行する（`proxy` を指定した場合は、動作しているか確認する） |

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

**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`

| ステータス | コード | メッセージ | 対処方法 |
| --- | --- | --- | --- |
| **403** | n/a | `User is suspended, deactivated or offboarded` | アカウントを利用できない。別のアカウントに切り替える |
| **401** | 32 | `Could not authenticate you` | `cookie` に指定した X セッションの認証情報を更新する |
| **403** | 465 | `not permitted to retweet an outdated Tweet` | ツイートが古すぎるためリツイートできない |
| 状況により異なる | 139 / 327 | すでにいいね済み・すでにリツイート済み | 現在の状態を確認する。操作を繰り返さない |
| **429** | n/a | レート制限 | 頻度を下げてから再試行する |
| **502 / 503** | n/a | 一時的な接続エラー | 再試行する |

### ツイートの削除

**POST** `/twitter/tweets/delete-batch`

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

| ステータス | メッセージ | 対処方法 |
| --- | --- | --- |
| **404** | `No status found with that ID` | すでに削除されているか、ID が不正 |
| **403** | 投稿者ではない | 削除できるのは自分のツイートのみ |
| **401** | `auth_token` が無効 | X セッションの認証情報を更新する |

### フォロー・フォロー解除

**POST** `/twitter/user/follow` · **DELETE** `/twitter/user/follow`

| ステータス | メッセージ | 対処方法 |
| --- | --- | --- |
| **404** | `User not found` | ハンドル名・ID を確認する |
| **403** | 制限されている | 使用中のアカウントまたは対象が操作を許可していない |
| **401** | `auth_token` が無効 | X セッションの認証情報を更新する |
| **429** | フォロー上限 | 待ってから再試行する |

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

**POST** `/twitter/profile`

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

| ステータス | メッセージ | 対処方法 |
| --- | --- | --- |
| **401** | `Invalid auth_token - could not fetch credentials` | X セッションの認証情報を更新する |
| **400** | 画像サイズ超過・不正な形式 | 画像を修正する |

## メディアの添付

ツイートの作成時や 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 の送信](/ja/api-reference/dm-endpoints/send-dm-api-v3-v3-twitter-send-dm-post) を参照してください。

| ステータス | コード | メッセージ | 対処方法 |
| --- | --- | --- | --- |
| **429** | 502 | `You've hit your daily message request limit. Subscribe to Premium for higher limits.` | 24 時間待つか、Premium アカウントを使用する |
| **403** | 476 | `Sender is not verified to send message requests` | アカウントが DM リクエストを送信できない |
| **403** | 349 | `Cannot send messages to this user` | 相手が自分からの DM を受け付けていない |
| **401** | 32 | `Could not authenticate you` | X セッションの認証情報を更新する |
| **404** | n/a | 会話・ユーザーが見つからない | 送信先を確認する |

## データの読み取り

**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}`

| ステータス | メッセージ | 対処方法 |
| --- | --- | --- |
| **404** | `Tweet not found: <id>` | ツイートが削除・非公開になっているか、ID が不正 |
| **404** | `Could not resolve userId for @<handle>` | ハンドル名が存在しない、変更された、またはアカウントが凍結されている |
| **404** | `Could not find user with ID: <id>` | ユーザー ID を確認する |
| **400** | `Missing required query param: <x>` | 必須パラメータを指定する |
| **429** | レート制限 | `retry_after` の時間だけ待ってから再試行する |

:::info
**地域によるコンテンツ制限。** X のアクセス制限は、指定したプロキシの出口の所在地など、場所によって異なる場合があります。レスポンスと対象の利用可否を確認してください。API アクセスによって地域制限を回避できるとは限りません。
:::

## 記事

**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` を保持し、失敗したステップだけを再試行できるよう、[段階的な記事作成フロー](/ja/api-reference/article-endpoints/article-create-draft-x-articles-draft-post) の使用を推奨します。

| ステータス | メッセージ | 対処方法 |
| --- | --- | --- |
| **403** | Premium が必要 | 記事の公開には X Premium アカウントが必要 |
| **404** | 記事が見つからない | 記事 ID を確認する |
| **401** | `auth_token` が無効 | X セッションの認証情報を更新する |
| **400** | コンテンツが無効 | 記事本文を修正する |

## 再試行ガイド

| 発生したエラー | 再試行するか | 注意事項 |
| --- | --- | --- |
| **429** | ✅ 指定された時間を待ってから | リクエストのレート制限に加え、アカウントの 1 日の上限にも従う |
| **422** | ❌ | 検証レスポンスに示されたフィールドを修正する |
| **500 / 502 / 503** | ✅ | 一時的なエラー。少し待って再試行する |
| **X コード 226** | 書き込み結果を確認してから | バックオフする。再試行前にアカウント制限を確認する |
| **401** | ❌ | API キーを修正するか、X セッションの認証情報を更新する |
| **403**（凍結・ロック） | ❌ | 別のアカウントを使用するか、先にロックを解除する |
| **404** | ❌ | ID・ハンドル名を確認する |
| **400 / 409** | ❌ | リクエストを修正する（パラメータ、メディアサイズ、重複した本文） |

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

:::warning 書き込みの再試行
書き込みでタイムアウト、空のレスポンス、または `5xx` が発生した後は、同じ操作を再送する前にタイムライン、DM 履歴、またはエンゲージメントの状態を確認してください。失敗レスポンスだけで、操作が実行されなかったと判断しないでください。
:::

## 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` の両方を確認してください。

## 関連ページ

- [エラー処理](/ja/guides/error-handling) — MCP、SDK、ページネーションの復旧
- [認証](/ja/authentication) — API キーと X セッションの認証情報
- [レート制限](/ja/guides/rate-limits) — バックオフとスループット
- [API 概要](/ja/api-reference/overview) — 現在のエンドポイントリファレンス