トラブルシューティング

このページでは、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()); }

鍵や identity が未設定のために暗号化または復号に失敗する

まず秘密鍵をロードし、次にセッション IDを設定します — あなたのユーザー ID と X 上のレコードの public_key_version です。encrypt_* および prepare_* メソッドはこの ID で署名します；セッション ID が未設定（かつ呼び出しごとの明示的な上書きもない状態）でそれらを呼び出すとエラーになります。

chat.unlock(passcode)  # or: chat.import_keys(blob)
chat.set_identity(my_user_id, signing_key_version)

await chat.unlock(passcode);
chat.setIdentity(myUserId, signingKeyVersion);

chat.import_keys(&blob)?;
chat.set_identity(&my_user_id, &signing_key_version);

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

chat.ImportKeys(blobBytes);
chat.SetIdentity(myUserId, signingKeyVersion);

chat.importKeys(blobBytes);
chat.setIdentity(myUserId, signingKeyVersion);

ローカルの公開鍵がアカウントの登録済み鍵と一致しない

クライアントはしばしば、「このデバイス上の鍵は、このアカウントに登録されている鍵のいずれかか？」 に答える必要があります — 復元またはインポート後に正しい public_key_version を採用するため、あるいはオンボーディングがすでに完了しているかを判断するためです。Chat XDK の get_public_keys の出力を API の public_key フィールドと文字列として比較すると、同じ鍵であっても常に失敗します。両者が異なるエンコーディングを使用しているためです:

API は登録時にアップロードされたとおりの鍵を保存して返します: DER (SPKI) エンコーディング — 固定のアルゴリズム識別子プレフィックスの後ろにある生の鍵
Chat XDK の get_public_keys は、そのプレフィックスなしの生の鍵だけを返します

同じ鍵、2 つの表記です。比較するには、両方を base64 デコードし、API のバイト列が SDK のバイト列で終わることを確認します（両側が同じエンコーディングを持つ場合に備え、完全一致も一致として扱います）:

import base64

def same_key(local_b64: str, server_b64: str) -> bool:
    local = base64.b64decode(local_b64)    # chat.get_public_keys()["identity"]
    server = base64.b64decode(server_b64)  # API row's "public_key"
    return local == server or (len(server) > len(local) and server.endswith(local))

const sameKey = (localB64: string, serverB64: string): boolean => {
  const local = Buffer.from(localB64, 'base64');   // chat.getPublicKeys().identity
  const server = Buffer.from(serverB64, 'base64'); // API row's public_key
  return local.equals(server) ||
    (server.length > local.length && server.subarray(server.length - local.length).equals(local));
};

fn same_key(local: &[u8], server: &[u8]) -> bool {
    local == server || (server.len() > local.len() && server.ends_with(local))
}

func sameKey(local, server []byte) bool {
    return bytes.Equal(local, server) ||
        (len(server) > len(local) && bytes.HasSuffix(server, local))
}

static bool SameKey(byte[] local, byte[] server) =>
    local.SequenceEqual(server) ||
    (server.Length > local.Length &&
     server.AsSpan(server.Length - local.Length).SequenceEqual(local));

static boolean sameKey(byte[] local, byte[] server) {
    if (Arrays.equals(local, server)) return true;
    if (server.length <= local.length) return false;
    byte[] tail = Arrays.copyOfRange(server, server.length - local.length, server.length);
    return Arrays.equals(tail, local);
}

一致したら、その行の public_key_version を set_identity に採用してください。バージョンを比較するとき（たとえば最新の鍵を選ぶ場合）は、数値として比較してください — バージョンはミリ秒のタイムスタンプで文字列長が可変なので、辞書順比較では誤ったものが選ばれます。

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

Message encrypted with key version '…' but no matching key found のようなエラーは、そのメッセージの conversation_key_version に対応する未加工の鍵を持っていないことを意味します。

extract_conversation_keys で conversation_key_change_event（ライブイベント）または meta.conversation_key_events（履歴）から鍵素材を復号する、またはこれらの blob を decrypt_events に含める — set_cache_keys(true) が有効な場合、decrypt_events は各会話の最新の検証済み鍵も保持し、後続の decrypt_event と encrypt_* の呼び出しでは省略できます
そのバージョンの会話鍵が追加されていること、およびあなたがまだ参加者であることを確認する（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_signing_keys 経由で保存もされていない
送信者がバージョンをローテーションした — 公開鍵を再取得する
受け入れフロアより下の鍵バージョンは決して検証されない
グループの鍵変更イベントで、署名者がすでにそのグループを離脱していると、その鍵はもはや配信されない — 離脱したメンバーによる鍵変更を参照

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);

返信の `reply_preview_validation` が `"Invalid"` になる

復号された返信には reply_preview_validation（"Valid" / "Invalid"；JavaScript は 'valid' / 'invalid' を使用）が付与される場合があります。Invalid は、メッセージ内の引用プレビューが埋め込まれた署名済みオリジナルイベントと一致しないことを意味します — 引用は信頼できないものとして扱い、引用コンテンツは検証済みのオリジナルからのみレンダリングしてください。メッセージ自体は別に検証されており依然として真正です；無効なプレビューによって例外がスローされることはありません。

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

古いイベントでの 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` を送信する — SDK が生成し、署名付きイベントに埋め込むため、他の値はすべて失敗します。再試行時には同じ暗号化ペイロードを再利用して、ID が二度と生成されないようにする
バージョンの不一致	`conversation_key_version` を使用する鍵と揃える；`set_identity` に渡す署名鍵バージョンを公開鍵レコードと揃える
パス 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_identity に渡した署名鍵バージョンが、公開鍵レコードの public_key_version と一致することを確認する
履歴が不完全な場合、復号する前に鍵変更のメタデータがスキップされないよう、すべてのイベントページをページングする

Getting Started

Products

Fundamentals

Partners & Customers

Resources

トラブルシューティング

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

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

鍵や identity が未設定のために暗号化または復号に失敗する

ローカルの公開鍵がアカウントの登録済み鍵と一致しない

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

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

復号と署名

復号が失敗する

署名が検証されない

返信の `reply_preview_validation` が `"Invalid"` になる

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

送信ペイロードの構築

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

メディアの暗号化と復号

安全なデバッグ

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

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

​鍵や identity が未設定のために暗号化または復号に失敗する

​ローカルの公開鍵がアカウントの登録済み鍵と一致しない

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

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

​復号と署名

​復号が失敗する

​署名が検証されない

​返信の reply_preview_validation が "Invalid" になる

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

​送信ペイロードの構築

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

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

​安全なデバッグ

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

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

鍵や identity が未設定のために暗号化または復号に失敗する

ローカルの公開鍵がアカウントの登録済み鍵と一致しない

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

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

復号と署名

復号が失敗する

署名が検証されない

返信の `reply_preview_validation` が `"Invalid"` になる

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

送信ペイロードの構築

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

メディアの暗号化と復号

安全なデバッグ