Solução de problemas

Esta página cobre problemas que são específicos da criptografia do X Chat e do Chat XDK — chaves, backup seguro de chaves, descriptografia/verificação e construção de payloads criptografados de envio. Para webhooks, OAuth, códigos de status HTTP e limites de taxa, use a documentação geral da X API e de autenticação.

Chaves e backup seguro de chaves

O desbloqueio falha (código de acesso inválido)

Confirme que o código de acesso corresponde ao usado com setup
Aguarde entre tentativas; realms limitam tentativas incorretas e podem travar a recuperação após muitas falhas

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

Criptografar ou descriptografar falha porque as chaves ou a identidade não foram definidas

Carregue as chaves privadas primeiro e depois defina a identidade da sessão — seu ID de usuário mais o public_key_version do seu registro no X. Os métodos encrypt_* e prepare_* assinam com ela; chamá-los sem identidade da sessão (e sem uma sobrescrita explícita por chamada) é um erro.

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

Sua chave pública local nunca corresponde às chaves registradas da conta

Os clientes frequentemente precisam responder “a chave neste dispositivo é uma das chaves registradas para esta conta?” — após uma restauração ou importação, para adotar o public_key_version correto, ou para decidir se o onboarding já aconteceu. Comparar a saída de get_public_keys do Chat XDK com o campo public_key da API como strings sempre falha, mesmo para a mesma chave, porque as duas usam codificações diferentes:

A API armazena e retorna a chave exatamente como o registro fez o upload: a codificação DER (SPKI) — a chave crua atrás de um prefixo fixo de identificador de algoritmo
O get_public_keys do Chat XDK retorna apenas a chave crua, sem esse prefixo

A mesma chave, duas grafias. Para comparar, decodifique ambas de base64 e verifique se os bytes da API terminam com os bytes do SDK (bytes idênticos também correspondem, caso ambos os lados algum dia mantenham a mesma codificação):

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

Depois de haver correspondência, adote o public_key_version daquela linha para set_identity. Ao comparar versões (por exemplo, para escolher a chave mais nova), compare numericamente — as versões são timestamps em milissegundos com comprimento de string variável, então uma comparação lexicográfica escolhe a errada.

Chave de conversa ausente para uma mensagem

Um erro como Message encrypted with key version '…' but no matching key found significa que você não tem a chave em bruto para o conversation_key_version daquela mensagem.

Descriptografe o material de chave a partir de conversation_key_change_event (eventos ao vivo) ou meta.conversation_key_events (histórico) com extract_conversation_keys, ou inclua esses blobs em decrypt_events — com set_cache_keys(true) habilitado, decrypt_events também retém a chave verificada mais recente de cada conversa para que chamadas posteriores de decrypt_event e encrypt_* possam omiti-la
Confirme que as chaves de conversa foram adicionadas para essa versão e que você ainda é um participante (veja Guia de introdução)

O par não tem chaves públicas

Pode ser que ele não tenha concluído o onboarding. Depois que ele se registrar, carregue public_key, signing_public_key, identity_public_key_signature e public_key_version a partir de Referência da API → Chaves de criptografia.

Descriptografia e assinaturas

A descriptografia falha

Chave de conversa em bruto obsoleta ou errada, ou versão de chave errada
String encoded_event incompleta
O tipo de evento não é uma mensagem criptografada que você pode tratar como conteúdo descriptografável

A assinatura não verifica

A verificação é fail-closed por padrão (reject_unverified = true): o SDK já rejeita eventos assinados não verificados, então uma falha aqui significa que as entradas de verificação estão erradas, e não que você precisa ativar a verificação. Causas comuns:

Entrada de chave de assinatura ausente ou incompleta para o remetente (todos os campos exigidos pelo Chat XDK — veja a referência do Chat XDK)
Nenhuma chave de assinatura passada na chamada e nenhuma armazenada via set_signing_keys
O remetente rotacionou versões — busque as chaves públicas dele novamente
Uma versão de chave abaixo do piso aceito nunca é verificada
Em um evento de mudança de chave de grupo, quem assinou já saiu do grupo, então suas chaves não são mais servidas — veja Mudanças de chave de membros que saíram

O setter set_reject_unverified existe para você desabilitar esse padrão (false, não recomendado). Se você o desativou antes, restaure o padrão fail-closed:

chat.set_reject_unverified(True)

chat.setRejectUnverified(true);

chat.set_reject_unverified(true);

chat.SetRejectUnverified(true)

chat.SetRejectUnverified(true);

chat.setRejectUnverified(true);

Uma resposta carrega `reply_preview_validation: "Invalid"`

Respostas descriptografadas podem carregar reply_preview_validation ("Valid" / "Invalid"; JavaScript usa 'valid' / 'invalid'). Invalid significa que a pré-visualização citada dentro da mensagem não corresponde ao evento original assinado que ela embute — trate a citação como não confiável e renderize o conteúdo citado apenas a partir do original validado. A mensagem em si é verificada separadamente e continua autêntica; nada é lançado por uma pré-visualização inválida.

Eventos antigos falham permanentemente na verificação

Erros como signature missing or no matching signing key ou uma incompatibilidade ECDSA em eventos antigos são permanentes. Assinaturas são imutáveis e verificadas reconstruindo o payload assinado a partir do próprio evento, então um evento que foi assinado sobre bytes diferentes (ou nunca foi assinado) falha em cada carregamento futuro — nenhuma nova tentativa, atualização de chave ou chamada de API pode curá-lo. Trate esses eventos como lápides, não como erros repetíveis. Rotacionar a chave de conversa inicia um histórico limpo e verificável a partir daquele ponto; novas mensagens não são afetadas.

Construindo o payload de envio

Estes erros são específicos da criptografia do X Chat (não são erros HTTP gerais):

Problema	Correção
Bytes de chave errados	Passe os bytes da chave de conversa em bruto para o Chat XDK, não a string de chave criptografada da API
Nomes de campos JSON errados	Mapeie `encrypted_content` → `encoded_message_create_event` e `encoded_event_signature` → `encoded_message_event_signature`
ID de mensagem errado	Envie o `message_id` do payload retornado — o SDK o gera e o embute no evento assinado, então qualquer outro valor falha. Em reenvios, reutilize o mesmo payload criptografado para que o ID nunca seja cunhado duas vezes
Versão incompatível	Alinhe `conversation_key_version` com a chave usada; alinhe a versão da chave de assinatura passada para `set_identity` com seu registro de chave pública
Forma do ID no path	Paths de URL ainda precisam do ID de conversa com hífen (`:` → `-`), mas para assinar o SDK aceita qualquer forma: `A:B`, `A-B` (em qualquer ordem), ou apenas o ID de usuário do destinatário — todos são canonicalizados para os mesmos bytes assinados

A API retorna 400 para uma chamada que altera estado

Toda chamada de chat que altera estado — adicionar ou rotacionar chaves de conversa, criar um grupo, adicionar membros — requer action_signatures no corpo da requisição, validado na fronteira da API. Uma entrada ausente ou malformada (cada uma precisa de message_id, encoded_message_event_detail e um message_event_signature com signature, public_key_version e signature_version) retorna imediatamente uma resposta HTTP 400 problem-details. Use os métodos prepare do SDK (prepare_conversation_key_change, prepare_group_create, prepare_group_members_change) e envie todas as assinaturas retornadas — criar grupo e adicionar membros retornam duas.

Criptografar e descriptografar mídia

Use a mesma chave de conversa (e versão) da mensagem que referencia o anexo
Trate respostas de download como texto cifrado até executar decrypt_stream
Deduza o tipo MIME após descriptografar; o Content-Type do download frequentemente não é o tipo real da imagem

Detalhes: Mídia.

Depuração segura

Ao investigar falhas de criptografia:

Registre apenas IDs de conversa, IDs de evento e versões de chave
Não registre texto simples, códigos de acesso, chaves privadas ou blobs de chave completos
Confirme que a versão de chave de assinatura passada para set_identity corresponde ao public_key_version no seu registro de chave pública
Para histórico incompleto, pagine todas as páginas de eventos para que os metadados de mudança de chave não sejam pulados antes de descriptografar

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Solução de problemas

Chaves e backup seguro de chaves

O desbloqueio falha (código de acesso inválido)

Criptografar ou descriptografar falha porque as chaves ou a identidade não foram definidas

Sua chave pública local nunca corresponde às chaves registradas da conta

Chave de conversa ausente para uma mensagem

O par não tem chaves públicas

Descriptografia e assinaturas

A descriptografia falha

A assinatura não verifica

Uma resposta carrega `reply_preview_validation: "Invalid"`

Eventos antigos falham permanentemente na verificação

Construindo o payload de envio

A API retorna 400 para uma chamada que altera estado

Criptografar e descriptografar mídia

Depuração segura

​Chaves e backup seguro de chaves

​O desbloqueio falha (código de acesso inválido)

​Criptografar ou descriptografar falha porque as chaves ou a identidade não foram definidas

​Sua chave pública local nunca corresponde às chaves registradas da conta

​Chave de conversa ausente para uma mensagem

​O par não tem chaves públicas

​Descriptografia e assinaturas

​A descriptografia falha

​A assinatura não verifica

​Uma resposta carrega reply_preview_validation: "Invalid"

​Eventos antigos falham permanentemente na verificação

​Construindo o payload de envio

​A API retorna 400 para uma chamada que altera estado

​Criptografar e descriptografar mídia

​Depuração segura

Chaves e backup seguro de chaves

O desbloqueio falha (código de acesso inválido)

Criptografar ou descriptografar falha porque as chaves ou a identidade não foram definidas

Sua chave pública local nunca corresponde às chaves registradas da conta

Chave de conversa ausente para uma mensagem

O par não tem chaves públicas

Descriptografia e assinaturas

A descriptografia falha

A assinatura não verifica

Uma resposta carrega `reply_preview_validation: "Invalid"`

Eventos antigos falham permanentemente na verificação

Construindo o payload de envio

A API retorna 400 para uma chamada que altera estado

Criptografar e descriptografar mídia

Depuração segura