トラブルシューティング

このページでは、X Chat の暗号化と Chat XDK に特有の問題（鍵、安全な鍵バックアップ、復号/検証、暗号化された送信ペイロードの構築）を扱います。 Webhook、OAuth、HTTP ステータスコード、レート制限については、一般的な X API および認証のドキュメントを参照してください。

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

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

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

try:
    chat.unlock(passcode)
except ValueError as e:
    print(e)  # may mention InvalidPin or guesses remaining

try {
  await chat.unlock(passcode);
} catch (e) {
  console.error((e as Error).message);
}

chat.unlock(passcode_bytes).await?;

if err := chat.Unlock(passcode, juiceboxConfigJSON); err != nil {
    log.Println(err)
}

try { chat.Unlock(passcode, juiceboxConfigJson); }
catch (Exception e) { Console.WriteLine(e.Message); }

try { chat.unlock(passcode, juiceboxConfigJson); }
catch (Exception e) { System.out.println(e.getMessage()); }

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

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

chat.unlock(passcode)  # or: chat.import_keys(blob)
chat.set_key_version(signing_key_version)

await chat.unlock(passcode);
chat.setKeyVersion(signingKeyVersion);

chat.import_keys(&blob)?;
chat.set_key_version(&signing_key_version);

blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
_ = chat.ImportKeys(blob)
chat.SetKeyVersion(signingKeyVersion)

chat.ImportKeys(blobBytes);
chat.SetKeyVersion(signingKeyVersion);

chat.importKeys(blobBytes);
chat.setKeyVersion(signingKeyVersion);

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

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

extract_conversation_keys で conversation_key_change_event（ライブイベント）または meta.conversation_key_events（履歴）から鍵素材を復号する、またはこれらの blob を decrypt_events に含める
そのバージョンの会話鍵が追加されていること、およびあなたがまだ参加者であることを確認する（Getting Started を参照）

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

彼らはオンボーディングを完了していない可能性があります。彼らが登録した後、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 リファレンスを参照）
送信者がバージョンをローテーションした — 公開鍵を再取得する
受け入れフロアより下の鍵バージョンは検証されない

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

chat.set_reject_unverified(True)

chat.setRejectUnverified(true);

chat.set_reject_unverified(true);

chat.SetRejectUnverified(true)

chat.SetRejectUnverified(true);

chat.setRejectUnverified(true);

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

古いイベントでの 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。

安全なデバッグ

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

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

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

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

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

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

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

​復号と署名

​復号が失敗する

​署名が検証されない

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

​送信ペイロードの構築

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

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

​安全なデバッグ