> ## 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.

# トラブルシューティング

> Chat XDK のエラー、セキュアな鍵バックアップからの復元、復号の失敗など、X Chat の暗号化に関するよくある問題を診断します。

このページでは、**X Chat の暗号化と Chat XDK に特有の**問題（鍵、安全な鍵バックアップ、復号/検証、暗号化された送信ペイロードの構築）を扱います。

Webhook、OAuth、HTTP ステータスコード、レート制限については、一般的な [X API](/x-api/introduction) および [認証](/fundamentals/authentication/overview) のドキュメントを参照してください。

***

## 鍵と安全な鍵バックアップ

### アンロックに失敗する（無効なパスコード）

* パスコードが `setup` で使用したものと一致するか確認する
* 試行の間で待機する；realm は間違った推測をレート制限し、多くの失敗の後に復元をロックすることがある

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    try:
        chat.unlock(passcode)
    except ValueError as e:
        print(e)  # may mention InvalidPin or guesses remaining
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    try {
      await chat.unlock(passcode);
    } catch (e) {
      console.error((e as Error).message);
    }
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    chat.unlock(passcode_bytes).await?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    if err := chat.Unlock(passcode, juiceboxConfigJSON); err != nil {
        log.Println(err)
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    try { chat.Unlock(passcode, juiceboxConfigJson); }
    catch (Exception e) { Console.WriteLine(e.Message); }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    try { chat.unlock(passcode, juiceboxConfigJson); }
    catch (Exception e) { System.out.println(e.getMessage()); }
    ```
  </Tab>
</Tabs>

### 鍵がロードされていないため暗号化または復号に失敗する

まず秘密鍵をロードし、次に X のレコードから公開鍵**バージョン**を設定します。

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    chat.unlock(passcode)  # or: chat.import_keys(blob)
    chat.set_key_version(signing_key_version)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await chat.unlock(passcode);
    chat.setKeyVersion(signingKeyVersion);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    chat.import_keys(&blob)?;
    chat.set_key_version(&signing_key_version);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
    _ = chat.ImportKeys(blob)
    chat.SetKeyVersion(signingKeyVersion)
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    chat.ImportKeys(blobBytes);
    chat.SetKeyVersion(signingKeyVersion);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    chat.importKeys(blobBytes);
    chat.setKeyVersion(signingKeyVersion);
    ```
  </Tab>
</Tabs>

### メッセージに対する会話鍵が欠落している

そのメッセージの `conversation_key_version` に対応する**未加工の**鍵を持っていません。

1. `extract_conversation_keys` で `conversation_key_change_event`（ライブイベント）または `meta.conversation_key_events`（履歴）から鍵素材を復号する、**または**これらの blob を `decrypt_events` に含める
2. そのバージョンの会話鍵が追加されていること、およびあなたがまだ参加者であることを確認する（[Getting Started](/xchat/getting-started#4-set-up-conversation-keys) を参照）

### ピアが公開鍵を持っていない

彼らはオンボーディングを完了していない可能性があります。彼らが登録した後、**API リファレンス → Encryption keys** から `public_key`、`signing_public_key`、`identity_public_key_signature`、`public_key_version` をロードしてください。

***

## 復号と署名

### 復号が失敗する

* 古いまたは間違った**未加工の**会話鍵、または間違った鍵バージョン
* 不完全な `encoded_event` 文字列
* イベントタイプが復号可能なコンテンツとして扱える暗号化メッセージではない

### 署名が検証されない

検証は**デフォルトで fail-closed**（`reject_unverified = true`）です: SDK はすでに検証されていない署名付きイベントを拒否しているため、ここでの失敗はチェックをオンにする必要があるという意味ではなく、検証入力が間違っていることを意味します。一般的な原因:

* **送信者**の署名鍵エントリが欠落または不完全（Chat XDK に必要なすべてのフィールド — [Chat XDK](/xchat/xchat-xdk) リファレンスを参照）
* 送信者がバージョンをローテーションした — 公開鍵を再取得する
* 受け入れフロアより下の鍵バージョンは検証されない

`set_reject_unverified` セッターは、このデフォルトから**オプトアウト**する（`false`、推奨されません）ために存在します。以前に無効化した場合は、fail-closed のデフォルトを復元してください:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    chat.set_reject_unverified(True)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    chat.setRejectUnverified(true);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    chat.set_reject_unverified(true);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    chat.SetRejectUnverified(true)
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    chat.SetRejectUnverified(true);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    chat.setRejectUnverified(true);
    ```
  </Tab>
</Tabs>

### 古いイベントが恒久的に検証に失敗する

**古い**イベントでの `signature missing or no matching signing key` や ECDSA の不一致のようなエラーは恒久的です。署名は不変であり、イベント自体から署名済みペイロードを再構築することで検証されるため、異なるバイトに対して署名された（またはそもそも署名されていない）イベントは、将来のすべてのロードで失敗します — 再試行、鍵の更新、または API 呼び出しでは治せません。これらのイベントは、再試行可能なエラーではなくトゥームストーンとして扱ってください。会話鍵をローテーションすると、その時点からクリーンで検証可能な履歴が始まります；新しいメッセージには影響しません。

***

## 送信ペイロードの構築

これらのミスは X Chat の暗号化に特有のものです（一般的な HTTP エラーではありません）:

| 問題               | 修正                                                                                                                                |
| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| 間違った鍵バイト         | API からの暗号化された鍵文字列ではなく、**未加工の**会話鍵バイトを Chat XDK に渡す                                                                                |
| 間違った JSON フィールド名 | `encrypted_content` → `encoded_message_create_event`、`encoded_event_signature` → `encoded_message_event_signature` にマップする         |
| メッセージ ID の欠落     | `message_id` を自分で生成し、同じ値をリクエストボディで送信する                                                                                            |
| バージョンの不一致        | `conversation_key_version` を使用する鍵と揃える；署名鍵バージョンを `set_key_version` / 公開鍵レコードと揃える                                                   |
| パス ID の形式        | URL パスには依然としてハイフン付きの会話 ID が必要（`:` → `-`）ですが、署名の場合、SDK は任意の形式を受け付けます: `A:B`、`A-B`（どちらの順序でも）、または受信者のユーザー ID だけ — すべては同じ署名バイトに正規化される |

### 状態を変更する呼び出しに対して API が 400 を返す

状態を変更するすべてのチャット呼び出し — 会話鍵の追加やローテーション、グループの作成、メンバーの追加 — は、リクエストボディに **`action_signatures`** を要求し、API 境界で検証されます。エントリの欠落や不正な形式（それぞれに `message_id`、`encoded_message_event_detail`、および `signature`、`public_key_version`、`signature_version` を持つ `message_event_signature` が必要）は、即座に HTTP 400 problem-details レスポンスを返します。SDK の prepare メソッド（`prepare_conversation_key_change`、`prepare_group_create`、`prepare_group_members_change`）を使い、返された**すべての**署名を送信してください — グループ作成とメンバー追加は 2 つ返します。

***

## メディアの暗号化と復号

* 添付を参照するメッセージと**同じ**会話鍵（およびバージョン）を使用する
* ダウンロードレスポンスは `decrypt_stream` を実行するまで**暗号文**として扱う
* MIME タイプは復号**後**に推測する；ダウンロードの `Content-Type` は実際の画像タイプでないことがよくある

詳細: [Media](/xchat/media)。

***

## 安全なデバッグ

暗号処理の失敗を調査する際:

* 会話 ID、イベント ID、鍵の**バージョン**のみをログに記録する
* 平文、パスコード、秘密鍵、または完全な鍵 blob は**ログに記録しない**
* `set_key_version` が公開鍵レコードの `public_key_version` と一致することを確認する
* 履歴が不完全な場合、復号する前に鍵変更のメタデータがスキップされないよう、**すべての**イベントページをページングする