> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# レスポンスコードとエラー

> デバッグのために X API が返す HTTP ステータスコード、エラーレスポンス形式、および一般的な 400、401、403、404、429、500 エラーのリファレンスです。

export const Button = ({href, children}) => {
  return <div className="not-prose">
    <a href={href}>
      <button className="x-btn">
        <span>{children}</span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

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

***

## HTTP ステータスコード

### 成功コード

| Code    | Meaning    | Description                   |
| :------ | :--------- | :---------------------------- |
| **200** | OK         | リクエストが成功                      |
| **201** | Created    | リソースが作成された（POST リクエスト）        |
| **204** | No Content | 成功したがレスポンスボディなし（DELETE リクエスト） |

### クライアントエラーコード

| Code    | Meaning           | Common causes                    |
| :------ | :---------------- | :------------------------------- |
| **400** | Bad Request       | 無効な JSON、不正なクエリ、必須パラメータの欠落       |
| **401** | Unauthorized      | 認証情報が無効または欠落                     |
| **403** | Forbidden         | 認証は有効だが、このリソースや操作の権限がない          |
| **404** | Not Found         | リソースが存在しないか削除された                 |
| **409** | Conflict          | ストリームにルールがない（filtered stream のみ） |
| **429** | Too Many Requests | rate limit または使用上限を超過            |

### サーバーエラーコード

| Code    | Meaning               | What to do                                                  |
| :------ | :-------------------- | :---------------------------------------------------------- |
| **500** | Internal Server Error | 待ってから再試行し、[status page](https://developer.x.com/status) を確認 |
| **502** | Bad Gateway           | 待ってから再試行                                                    |
| **503** | Service Unavailable   | X が過負荷。待ってから再試行                                             |
| **504** | Gateway Timeout       | 待ってから再試行                                                    |

***

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

エラーレスポンスには構造化された詳細が含まれます。

```json theme={null}
{
  "title": "Invalid Request",
  "detail": "The 'query' parameter is required.",
  "type": "https://api.x.com/2/problems/invalid-request"
}
```

| Field    | Description     |
| :------- | :-------------- |
| `type`   | エラータイプを識別する URI |
| `title`  | エラーの短い説明        |
| `detail` | このエラーに固有の説明     |

エラータイプに応じて追加フィールドが存在する場合があります。

***

## エラータイプ

| Type                              | Description                 |
| :-------------------------------- | :-------------------------- |
| `about:blank`                     | 一般的なエラー（HTTP ステータスコードを参照）   |
| `.../invalid-request`             | 不正なリクエストや無効なパラメータ           |
| `.../resource-not-found`          | Post、ユーザー、その他のリソースが存在しない    |
| `.../not-authorized-for-resource` | 非公開/保護コンテンツへのアクセス権がない       |
| `.../client-forbidden`            | アプリが登録されていないか、必要なアクセス権を持たない |
| `.../usage-capped`                | 使用上限を超過                     |
| `.../rate-limit-exceeded`         | rate limit を超過              |
| `.../streaming-connection`        | ストリーム接続の問題                  |
| `.../rule-cap`                    | filtered stream のルールが多すぎる   |
| `.../invalid-rules`               | ルールの構文エラー                   |
| `.../duplicate-rules`             | ルールが既に存在する                  |

***

## 部分的なエラー

一部のリクエストは部分的に成功することがあります。200 レスポンスに `data` と `errors` の両方が含まれることがあります。

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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"
    }
  ]
}
```

これは複数のリソースをリクエストして、一部が利用できないときに発生します。

***

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

<Accordion title="401 Unauthorized">
  **認証を確認してください:**

  * エンドポイントに対して正しい認証方式を使用しているか確認
  * 認証情報が再生成されていないか確認
  * `Authorization` ヘッダーの形式を確認
  * OAuth 1.0a の場合、署名の計算を検証

  [認証ガイド →](/resources/fundamentals/authentication/overview)
</Accordion>

<Accordion title="403 Forbidden">
  **アクセス権を確認してください:**

  * このエンドポイントへのアクセス権をアプリが持っているか確認
  * 一部のエンドポイントは特定の登録や承認が必要
  * User-context エンドポイントには適切な OAuth スコープが必要
  * リソースが非公開または保護されている可能性
</Accordion>

<Accordion title="429 Too Many Requests">
  **Rate limit に達しました:**

  * `x-rate-limit-reset` ヘッダーで再試行時刻を確認
  * 指数バックオフを実装
  * レスポンスのキャッシュを検討
  * 時間ウィンドウ全体にリクエストを分散

  [Rate limits ガイド →](/x-api/fundamentals/rate-limits)
</Accordion>

<Accordion title="400 Bad Request">
  **リクエストを修正してください:**

  * JSON 構文を検証
  * 必須パラメータの欠落を確認
  * パラメータの型を確認（文字列 vs. 数値）
  * クエリ内の特殊文字をエスケープ
</Accordion>

<Accordion title="期待した post が見つからない">
  **以下の要因を確認してください:**

  * 保護されたアカウントの post は認可がある場合のみ表示されます
  * 削除された post は 404 を返します
  * 一部の post は特定地域で withhold されます
  * 検索クエリの構文が正しいか確認
</Accordion>

<Accordion title="ストリームの切断">
  **再接続を処理:**

  * バックオフ付きの自動再接続を実装
  * 欠落データには Recovery 機能を使用
  * バッファ満杯による切断を確認（クライアントの消費が遅すぎる）
  * ストリームルールが少なくとも 1 つ存在することを確認

  [ストリーミングガイド →](/x-api/fundamentals/handling-disconnections)
</Accordion>

***

## Rate limit のヘッダー

すべてのレスポンスには rate limit の情報が含まれます。

```
x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800
```

| Header                   | Description                |
| :----------------------- | :------------------------- |
| `x-rate-limit-limit`     | 現在のウィンドウでの最大リクエスト数         |
| `x-rate-limit-remaining` | 残りのリクエスト数                  |
| `x-rate-limit-reset`     | ウィンドウがリセットされる Unix タイムスタンプ |

***

## ベストプラクティス

<CardGroup cols={2}>
  <Card title="ステータスコードを確認" icon="square-check">
    レスポンスボディをパースする前に必ず HTTP ステータスを確認してください。
  </Card>

  <Card title="部分エラーを処理" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" width="24" height="24" data-path="icons/xds/icon-warning.svg">
    200 レスポンスでも `errors` 配列を確認してください。
  </Card>

  <Card title="再試行ロジックを実装" icon="arrows-rotate">
    429 と 5xx エラーには指数バックオフを使用してください。
  </Card>

  <Card title="リクエスト詳細をログ" icon="file-lines">
    デバッグ用にリクエスト ID とタイムスタンプを記録してください。
  </Card>
</CardGroup>

***

## ヘルプを得る

エラーについて質問する際は、以下を含めてください。

* API エンドポイント URL
* リクエストヘッダー（認証情報はマスク）
* 完全なエラーレスポンス
* 期待していた挙動
* 試したステップ

<CardGroup cols={2}>
  <Card title="Developer Forum" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=ce6313d8c0b7b4e5363f2ce80b89f7e4" href="https://devcommunity.x.com" width="24" height="24" data-path="icons/xds/icon-chat-unread.svg">
    質問して解決策を検索。
  </Card>

  <Card title="API Status" icon="signal" href="https://developer.x.com/status">
    既知の問題を確認。
  </Card>
</CardGroup>