Solución de problemas

Esta página cubre problemas que son específicos del cifrado de X Chat y del Chat XDK—claves, copia de seguridad segura de claves, descifrar/verificar, y construcción de payloads de envío cifrados. Para webhooks, OAuth, códigos de estado HTTP y límites de tasa, usa la documentación general de la X API y de autenticación.

Claves y copia de seguridad segura de claves

Falla el unlock (código de acceso inválido)

Confirma que el código de acceso coincide con el usado con setup
Espera entre intentos; los realms limitan por tasa los intentos erróneos y pueden bloquear la recuperación tras demasiados fallos

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

Cifrar o descifrar falla porque las claves o la identidad no están configuradas

Carga primero las claves privadas, luego configura la identidad de sesión—tu user id más el public_key_version de tu registro en X. Los métodos encrypt_* y prepare_* firman con ella; llamarlos sin identidad de sesión (y sin una anulación explícita por llamada) es un error.

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

Falta la clave de conversación para un mensaje

Un error como Message encrypted with key version '…' but no matching key found significa que no tienes la clave en bruto para el conversation_key_version de ese mensaje.

Descifra el material de clave desde conversation_key_change_event (eventos en vivo) o meta.conversation_key_events (historial) con extract_conversation_keys, o incluye esos blobs en decrypt_events—con set_cache_keys(true) habilitado, decrypt_events también retiene la última clave verificada de cada conversación para que las llamadas posteriores decrypt_event y encrypt_* puedan omitirla
Confirma que se añadieron claves de conversación para esa versión y que sigues siendo participante (consulta Primeros pasos)

El par no tiene claves públicas

Es posible que no haya terminado el onboarding. Después de que se registre, carga public_key, signing_public_key, identity_public_key_signature y public_key_version desde API reference → Encryption keys.

Descifrado y firmas

Falla el descifrado

Clave de conversación en bruto obsoleta o incorrecta, o versión de clave incorrecta
Cadena encoded_event incompleta
El tipo de evento no es un mensaje cifrado que puedas tratar como contenido descifrable

La firma no se verifica

La verificación es fail-closed por defecto (reject_unverified = true): el SDK ya rechaza eventos firmados no verificados, así que un fallo aquí significa que las entradas de verificación son incorrectas, no que necesites activar la comprobación. Causas comunes:

Entrada de clave de firma faltante o incompleta para el remitente (todos los campos requeridos por el Chat XDK—consulta la referencia del Chat XDK)
No se pasaron claves de firma en la llamada y no hay ninguna almacenada mediante set_signing_keys
El remitente rotó versiones—vuelve a obtener sus claves públicas
Una versión de clave por debajo del mínimo aceptado nunca se verifica

El setter set_reject_unverified existe para desactivar este comportamiento predeterminado (false, no recomendado). Si lo desactivaste antes, restaura el predeterminado fail-closed:

chat.set_reject_unverified(True)

chat.setRejectUnverified(true);

chat.set_reject_unverified(true);

chat.SetRejectUnverified(true)

chat.SetRejectUnverified(true);

chat.setRejectUnverified(true);

Una respuesta lleva `reply_preview_validation: "Invalid"`

Las respuestas descifradas pueden llevar reply_preview_validation ("Valid" / "Invalid"; JavaScript usa 'valid' / 'invalid'). Invalid significa que la vista previa citada dentro del mensaje no coincide con el evento original firmado que incrusta—trata la cita como no confiable y renderiza el contenido citado solo desde el original validado. El mensaje en sí se verifica por separado y sigue siendo auténtico; nada se lanza por una vista previa inválida.

Los eventos antiguos fallan permanentemente la verificación

Errores como signature missing or no matching signing key o una discrepancia ECDSA en eventos antiguos son permanentes. Las firmas son inmutables y se verifican reconstruyendo el payload firmado a partir del propio evento, así que un evento que fue firmado sobre bytes diferentes (o nunca firmado) fallará en cada carga futura—ningún reintento, refresco de claves ni llamada a la API puede sanarlo. Trata estos eventos como tombstones, no como errores reintentables. Rotar la clave de conversación inicia un historial limpio y verificable a partir de ese punto hacia adelante; los nuevos mensajes no se ven afectados.

Construyendo el payload de envío

Estos errores son específicos del cifrado de X Chat (no son errores HTTP generales):

Problema	Solución
Bytes de clave incorrectos	Pasa los bytes de la clave de conversación en bruto al Chat XDK, no la cadena de clave cifrada de la API
Nombres de campo JSON incorrectos	Mapea `encrypted_content` → `encoded_message_create_event` y `encoded_event_signature` → `encoded_message_event_signature`
ID de mensaje incorrecto	Envía el `message_id` del payload devuelto—el SDK lo genera y lo incrusta en el evento firmado, así que cualquier otro valor falla. En los reintentos, reutiliza el mismo payload cifrado para que el ID nunca se genere dos veces
Discrepancia de versión	Alinea `conversation_key_version` con la clave que uses; alinea la versión de la clave de firma pasada a `set_identity` con tu registro de public-key
Forma del ID en la ruta	Las rutas URL todavía necesitan el ID de conversación con guiones (`:` → `-`), pero para firmar el SDK acepta cualquier forma: `A:B`, `A-B` (en cualquier orden), o el user id del destinatario a secas—todo se canonicaliza a los mismos bytes firmados

La API devuelve 400 para una llamada que cambia el estado

Cada llamada de chat que cambia el estado—añadir o rotar claves de conversación, crear un grupo, añadir miembros—requiere action_signatures en el cuerpo de la solicitud, validadas en el límite de la API. Una entrada faltante o mal formada (cada una necesita message_id, encoded_message_event_detail y una message_event_signature con signature, public_key_version y signature_version) devuelve una respuesta problem-details HTTP 400 de inmediato. Usa los métodos prepare del SDK (prepare_conversation_key_change, prepare_group_create, prepare_group_members_change) y envía todas las firmas devueltas—group create y member adds devuelven dos.

Cifrado y descifrado de multimedia

Usa la misma clave de conversación (y versión) que el mensaje que hace referencia al adjunto
Trata las respuestas de descarga como texto cifrado hasta ejecutar decrypt_stream
Infere el tipo MIME después de descifrar; el Content-Type de descarga a menudo no es el tipo real de la imagen

Detalles: Multimedia.

Depuración segura

Al investigar fallos de criptografía:

Registra en logs los IDs de conversación, los IDs de evento y las versiones de claves únicamente
No registres en logs texto plano, códigos de acceso, claves privadas ni blobs de clave completos
Confirma que la versión de la clave de firma pasada a set_identity coincide con el public_key_version de tu registro de public-key
Para historial incompleto, pagina todas las páginas de eventos para no saltar los metadatos de key-change antes de descifrar

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Solución de problemas

Claves y copia de seguridad segura de claves

Falla el unlock (código de acceso inválido)

Cifrar o descifrar falla porque las claves o la identidad no están configuradas

Falta la clave de conversación para un mensaje

El par no tiene claves públicas

Descifrado y firmas

Falla el descifrado

La firma no se verifica

Una respuesta lleva `reply_preview_validation: "Invalid"`

Los eventos antiguos fallan permanentemente la verificación

Construyendo el payload de envío

La API devuelve 400 para una llamada que cambia el estado

Cifrado y descifrado de multimedia

Depuración segura

​Claves y copia de seguridad segura de claves

​Falla el unlock (código de acceso inválido)

​Cifrar o descifrar falla porque las claves o la identidad no están configuradas

​Falta la clave de conversación para un mensaje

​El par no tiene claves públicas

​Descifrado y firmas

​Falla el descifrado

​La firma no se verifica

​Una respuesta lleva reply_preview_validation: "Invalid"

​Los eventos antiguos fallan permanentemente la verificación

​Construyendo el payload de envío

​La API devuelve 400 para una llamada que cambia el estado

​Cifrado y descifrado de multimedia

​Depuración segura

Claves y copia de seguridad segura de claves

Falla el unlock (código de acceso inválido)

Cifrar o descifrar falla porque las claves o la identidad no están configuradas

Falta la clave de conversación para un mensaje

El par no tiene claves públicas

Descifrado y firmas

Falla el descifrado

La firma no se verifica

Una respuesta lleva `reply_preview_validation: "Invalid"`

Los eventos antiguos fallan permanentemente la verificación

Construyendo el payload de envío

La API devuelve 400 para una llamada que cambia el estado

Cifrado y descifrado de multimedia

Depuración segura