Solução de problemas

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

Chaves e backup seguro de chave

Unlock falha (código de acesso inválido)

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

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

Criptografia ou descriptografia falha porque as chaves ou a identidade não estão 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 uma identidade de sessão (e sem um override explícito 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

Clientes muitas vezes precisam responder à pergunta “a chave neste dispositivo é uma das chaves registradas nesta conta?” — após uma restauração ou importação, para adotar o public_key_version correto, ou para decidir se o onboarding já ocorreu. 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 os dois 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 em bruto atrás de um prefixo fixo de identificador de algoritmo
O get_public_keys do Chat XDK retorna a chave em bruto sozinha, sem esse prefixo

Mesma chave, duas grafias. Para comparar, decodifique ambos em base64 e verifique se os bytes da API terminam com os bytes do SDK (bytes idênticos também correspondem, caso os dois lados venham a manter 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);
}

Uma vez que houver correspondência, adote o public_key_version dessa linha para set_identity. Ao comparar versões (por exemplo, para escolher a chave mais recente), compare numericamente — as versões são timestamps em milissegundos com comprimento de string variável, então a 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 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, de modo que chamadas posteriores de decrypt_event e encrypt_* podem omiti-la
Confirme que as chaves de conversa foram adicionadas para aquela versão e que você ainda é um participante (veja Primeiros passos)

O peer não tem chaves públicas

Talvez 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 em Referência da API → Chaves de criptografia.

Descriptografia e assinaturas

Descriptografia falha

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

A assinatura não é verificada

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, não que você precisa ligar a checagem. 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 nem armazenada via set_signing_keys
O remetente rotacionou as versões — busque suas chaves públicas novamente
Uma versão de chave abaixo do piso aceito nunca é verificada
Em um evento de mudança de chave de grupo, o signatário deixou o grupo desde então, portanto suas chaves não são mais servidas—veja Mudanças de chave por membros que saíram

O setter set_reject_unverified existe para desabilitar esse padrão (false, não recomendado). Se você o desabilitou anteriormente, 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 traz `reply_preview_validation: "Invalid"`

Respostas descriptografadas podem trazer reply_preview_validation ("Valid" / "Invalid"; JavaScript usa 'valid' / 'invalid'). Invalid significa que o preview citado dentro da mensagem não corresponde ao evento original assinado que ela incorpora — 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 um preview inválido.

Eventos antigos falham permanentemente na verificação

Erros como signature missing or no matching signing key ou um mismatch de 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 assinado sobre bytes diferentes (ou nunca assinado) falha em toda carga futura — nenhuma retentativa, atualização de chave ou chamada de API pode consertá-lo. Trate esses eventos como tombstones, não como erros com retentativa. Rotacionar a chave da conversa inicia um histórico limpo e verificável a partir desse ponto; novas mensagens não são afetadas.

Montando o payload de envio

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

Problema	Correção
Bytes de chave incorretos	Passe os bytes da chave da conversa em bruto para o Chat XDK, não a string de chave criptografada da API
Nomes de campo 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 incorpora ao evento assinado, então qualquer outro valor falha. Em retentativas, reutilize o mesmo payload criptografado para que o ID nunca seja gerado duas vezes
Descompasso de versão	Alinhe `conversation_key_version` com a chave que você usa; alinhe a versão da chave de assinatura passada para `set_identity` com seu registro de chave pública
Forma do ID no caminho	Caminhos de URL ainda precisam do ID da conversa com hífen (`:` → `-`), mas para assinatura o SDK aceita qualquer forma: `A:B`, `A-B` (qualquer ordem) ou apenas o ID do usuário destinatário — todos canonizam para os mesmos bytes assinados

A API retorna 400 para uma chamada que muda estado

Toda chamada de chat que muda estado — adicionar ou rotacionar chaves de conversa, criar um grupo, adicionar membros — requer action_signatures no corpo da requisição, validado na borda 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 uma resposta problem-details HTTP 400 imediatamente. Use os métodos prepare do SDK (prepare_conversation_key_change, prepare_group_create, prepare_group_members_change) e envie todas as assinaturas retornadas — criação de grupo e adição de membros retornam duas.

Criptografia e descriptografia de 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
Infira 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 do seu registro de chave pública
Para histórico incompleto, pagine todas as páginas de eventos para que 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 chave

Unlock falha (código de acesso inválido)

Criptografia ou descriptografia falha porque as chaves ou a identidade não estão definidas

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

Chave de conversa ausente para uma mensagem

O peer não tem chaves públicas

Descriptografia e assinaturas

Descriptografia falha

A assinatura não é verificada

Uma resposta traz `reply_preview_validation: "Invalid"`

Eventos antigos falham permanentemente na verificação

Montando o payload de envio

A API retorna 400 para uma chamada que muda estado

Criptografia e descriptografia de mídia

Depuração segura

​Chaves e backup seguro de chave

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

​Criptografia ou descriptografia falha porque as chaves ou a identidade não estão definidas

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

​Chave de conversa ausente para uma mensagem

​O peer não tem chaves públicas

​Descriptografia e assinaturas

​Descriptografia falha

​A assinatura não é verificada

​Uma resposta traz reply_preview_validation: "Invalid"

​Eventos antigos falham permanentemente na verificação

​Montando o payload de envio

​A API retorna 400 para uma chamada que muda estado

​Criptografia e descriptografia de mídia

​Depuração segura

Chaves e backup seguro de chave

Unlock falha (código de acesso inválido)

Criptografia ou descriptografia falha porque as chaves ou a identidade não estão definidas

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

Chave de conversa ausente para uma mensagem

O peer não tem chaves públicas

Descriptografia e assinaturas

Descriptografia falha

A assinatura não é verificada

Uma resposta traz `reply_preview_validation: "Invalid"`

Eventos antigos falham permanentemente na verificação

Montando o payload de envio

A API retorna 400 para uma chamada que muda estado

Criptografia e descriptografia de mídia

Depuração segura