Solução de problemas

Comece pelo sintoma que você vê. Cada seção traz as causas prováveis, como diferenciá-las e a correção, com link para a página que tem a regra completa. O FingerTrackID nunca bloqueia o seu produto: enquanto você corrige qualquer um destes casos, o seu login e toda outra ação de negócio seguem o caminho normal (orientações de integração).

Confira primeiro a saúde da integração

No console, abra Integração e saúde para a aplicação (a tela). Ela cobre as últimas 24 horas registradas; os números não são em tempo real.

• Última coleta mostra um horário recente em vez de nenhuma coleta na janela. Nenhuma coleta aponta para o lado do navegador: veja o Web SDK não coleta nada.
• Em Da coleta à avaliação, Coletas aceitas cresce com os seus logins e Correlacionadas (avaliações que encontraram a coleta do navegador delas) fica perto de Avaliações. Coletas sem avaliações correlacionadas apontam para a passagem do navegador para o seu backend: veja as avaliações chegam sem evidência do navegador.
• A saúde Sem dados do SDK significa que chegaram avaliações na janela e nenhuma trouxe o contexto do SDK, então nenhuma recebeu nota.
• Credenciais de servidor mostra o key_id e o estado de cada credencial, Origens das páginas as origens de site em que o SDK pode coletar, e Limite de requisições a taxa em vigor.

Para um acesso específico, abra-o em Acessos: com evidência do navegador, Cobertura de evidência fica acima de zero, o indicador Automação (robô) mostra Detectado ou Não detectado em vez de Não avaliado, e as limitações não incluem Coletor não carregado. A lista completa de verificações está em confira se a evidência do SDK chega.

O Web SDK não coleta nada

Toda chamada do SDK que falha devolve UNAVAILABLE com um reason (ou, com o helper, um failure com o seu stage e o seu reason); initializeSdk() e createEvent() lançam exceção em vez disso. Registre-os em log: o motivo diferencia a maioria das causas (motivos de falha).

O que você vê	Causa provável	Correção
Nenhuma requisição chega ao seu domínio de coleta, e a configuração em Início não terminou	O domínio de coleta ainda não está ativo. Sem um domínio de coleta ativo o SDK não é habilitado para a sua aplicação, e publicar o DNS sozinho não o ativa	Acompanhe a etapa Confirmar o domínio de coleta até mostrar Concluído, e Configurar a coleta web até Concluída (domínio de coleta)
A etapa espera em Depende de você, ou um registro mostra Ainda não encontrado	Um registro DNS está faltando, tem outro nome, responde com mais de um valor ou está atrás de um proxy; ou a sua política CAA não permite o certificado	Publique os três registros exatamente como aparecem, só DNS, sem nada na frente; permita pki.goog e letsencrypt.org na CAA; depois escolha Verificar agora (os registros, como conferir)
Uma etapa automática mostra Algo travou	Uma etapa da plataforma não andou por 30 minutos	Fale com o suporte informando a referência do pedido mostrada em Início
TRANSPORT_ERROR numa página cuja origem não está em Origens das páginas	A origem da página não é uma das origens permitidas da aplicação: o domínio de coleta responde 403 origin-not-allowed sem aprovação de CORS, e o navegador esconde essa resposta	Adicione a origem HTTPS exata em Integração e saúde › Origens das páginas (até 10, todas sob o domínio de coleta; a mudança vale na hora)
TRANSPORT_ERROR, e o console do navegador relata uma violação de CSP	O seu connect-src não lista a origem de coleta exata	Adicione-a ao connect-src; o SDK não precisa de entrada em script-src (a CSP do seu site)
TRANSPORT_ERROR, e a requisição OPTIONS ao domínio de coleta responde 400	Uma instrumentação da página adiciona cabeçalhos de rastreamento às requisições do SDK	Deixe a origem de coleta fora da propagação de rastreamento (cabeçalhos de rastreamento)
TRANSPORT_ERROR só para alguns visitantes	Uma extensão de bloqueio no navegador, ou a rede	Nada a mudar na sua configuração: siga com contexto null, e a avaliação desse acesso fica inconclusiva
AUTHENTICATION_FAILED numa origem permitida	O publicKey não é desta aplicação (pub_app_…), ou a versão do SDK não é aquela para a qual a coleta da sua aplicação está configurada	Use a chave pública emitida no dash; instale a versão que o dash oferece, e fale com o suporte antes de trocá-la (atualização do SDK)
INVALID_RESPONSE	Um proxy, CDN ou WAF na frente do domínio de coleta alterou a resposta	Mantenha o CNAME de coleta só como DNS
TRANSPORT_ERROR ou INVALID_RESPONSE logo na abertura da sessão, depois de uma mudança no build	Uma opção do minificador que quebra o SDK, como compress.unsafe_math (medido no SDK 0.2.0)	Exclua o pacote do SDK dessa minificação ou desligue a opção (instalação)
RATE_LIMITED	Por exemplo, sessões novas demais, ou mais de 1000 sessões vivas na aplicação	Prepare só na primeira intenção de um formulário avaliado, nunca no carregamento da página, e chame close() ao terminar (limites de sessão)
initializeSdk() lança INVALID_CONFIGURATION	A configuração não é exatamente publicKey e collectionOrigin, uma origem HTTPS sem caminho	Corrija as duas chaves (initializeSdk)
initializeSdk() lança UNSUPPORTED_RUNTIME	A página não é HTTPS, ou falta ao navegador Fetch, aleatoriedade criptográfica ou um relógio monotônico	Siga com contexto null

O SDK é entregue só como o pacote privado empacotado no seu frontend. O FingerTrackID não serve script do SDK, então uma página que o carrega de uma URL ou de uma CDN pública não coleta nada.

As avaliações chegam sem evidência do navegador

A resposta é INCONCLUSIVE com trust_score: null, recommendation_basis INSUFFICIENT_EVIDENCE e o MONITOR de fallback; os 13 indicadores são NOT_EVALUATED com COLLECTOR_NOT_LOADED, e device_intelligence_snapshot_id e sdk_version são null. No perfil gerenciado de produção atual, uma avaliação gravada sem event_context_token é sempre assim (quando o navegador não tem contexto do evento).

• O seu backend envia null. O navegador envia o token e o seu expiresAt na requisição de negócio que já faz; o seu backend copia o token para event_context_token. Confira se o campo é repassado, e se a maioria dos logins nos logs do seu backend leva um token. Um login sem token precisa ter um motivo registrado, como WAIT_EXCEEDED numa rede lenta, e não um mesmo código fixo em todo login.
• O navegador não tinha token. O SDK falhou (veja acima), ou o contexto foi pego tarde demais: um envio sem nada preparado precisa de pelo menos três idas e voltas antes de existir um token. Chame prefetch() no primeiro foco ou pointer-down do formulário (o ciclo de vida).
• Logins por redirecionamento (provedores sociais ou OAuth) perdem o contexto, a menos que ele seja pego antes do redirecionamento ou coletado depois do callback (redirecionamentos de login).
• O cliente foi fechado cedo demais. Chamar close() antes de o seu backend responder encerra a sessão que emitiu o token, e um token cuja avaliação ainda não foi gravada deixa de funcionar.
• A API responde 400 event-context-invalid. O token expirou, já foi usado ou é de outro escopo (por exemplo, coletado para outra aplicação). Nada é gravado. Não repita o mesmo corpo: avalie o evento mais uma vez como uma operação nova com event_context_token: null (event-context-invalid).

Um token é de uso único, um por evento de negócio, e a avaliação que o leva precisa ser gravada antes do seu expiresAt. A janela de evidência é de 60 ou 300 segundos a partir de quando a coleta chega ao FingerTrackID, conforme a sua aplicação; toda resposta a mostra em data_freshness.maximum_required_age_ms (a janela de evidência). Se event-context-invalid for frequente, colete mais perto da ação.

401 em POST /v1/assessments

O type diferencia três casos. timestamp-out-of-window e request-replayed só respondem a uma requisição cuja assinatura foi verificada para uma credencial conhecida: se você os vê, a sua assinatura está certa.

authentication-failed

A falha uniforme, sem nova tentativa: a resposta nunca diz qual parte estava errada. Trate-a como erro de configuração e confira, nesta ordem:

1. O segredo. A chave é o conjunto de bytes decodificados do segredo, decodeSecret(text, 'hex'), nunca o texto hexadecimal. Use o segredo entregue com aquele key_id: depois de Trocar segredo a nova credencial tem um novo key_id, e a anterior é revogada ao fim de uma sobreposição de no máximo 24 horas.
2. Os bytes. O hash do corpo cobre os bytes exatos que você envia. Monte o corpo com uma única chamada de JSON.stringify e envie esses bytes; serializar de novo depois de assinar dá 401.
3. A string canônica. Exatamente dez linhas separadas por LF, sem LF no final, a nona vazia; o caminho é literalmente /v1/assessments (a string canônica).
4. Os cabeçalhos. X-FTID-Signature: v1=<key_id>:<mac>, uma única assinatura, com um MAC de 64 caracteres em minúsculas; key_id e request_id são UUIDv7 em minúsculas. X-Client-Id, X-Signature, X-Timestamp e X-Nonce são recusados com 401.
5. O estado da credencial. Em Integração e saúde › Credenciais de servidor, a credencial precisa estar ativa, não revogada nem suspensa. Uma credencial ainda aguardando instalação segura não pode ser usada. Um cliente que continuou repetindo 429 sem esperar fica bloqueado por pelo menos 10 minutos, e nesse tempo toda requisição recebe 401.

Rode a autoverificação de referência no Node.js que roda o seu backend: node ftid-hmac-v1-self-check.mjs precisa imprimir OK e o MAC do vetor de teste. Se imprimir, o assinador funciona, e a causa é o segredo, o key_id ou os bytes que você envia (assinador de referência).

timestamp-out-of-window

Admite nova tentativa. X-FTID-Timestamp é o segundo em que você assina a tentativa, não o occurred_at do evento, e precisa estar dentro de ±300 s do relógio do servidor. Sincronize o relógio do seu backend (NTP) e envie uma nova tentativa. Um occurred_at fora de ±300 s é outro erro, 400 occurred-at-out-of-window.

request-replayed

Admite nova tentativa. Um request_id foi reutilizado. Ele é o nonce antirreplay: gere um novo a cada tentativa, inclusive depois de 401, 403, 429 ou 503, com crypto.randomUUIDv7(), nunca crypto.randomUUID(), que gera a versão 4. Depois corrija o gerador que o repetiu.

403 forbidden

Você está autenticado, mas a credencial não tem a capability da rota. As capabilities de uma credencial ficam congeladas na sua versão, então não dá para acrescentar uma a ela: crie no console uma credencial de servidor com essa permissão. As rotas de feedback precisam de action:write e outcome:write (forbidden).

429 rate-limited

O seu cliente de servidor passou da taxa: 5 requisições por segundo com rajada de 10 no nível padrão (limites). Espere o Retry-After (segundos inteiros, hoje 1) e envie uma nova tentativa com o mesmo corpo, um request_id novo, o timestamp atual e uma nova assinatura. Reutilizar o request_id antigo dá 401 request-replayed, e repetir sem esperar esgota o orçamento de segurança e bloqueia a credencial por pelo menos 10 minutos.

Para aumentar a taxa, abra Integração e saúde › Limite de requisições e escolha Pedir aumento de limite, como Administrador da empresa ou Gestor de integração; o console oferece até 10 por segundo, aprovado na hora. Para mais, fale com o suporte em contato@fingertrackid.com. Uma saturação momentânea do serviço é 503 assessment-unavailable, repetida do mesmo jeito.

Muitos resultados inconclusivos

INCONCLUSIVE é uma afirmação sobre a evidência, não sobre a pessoa: nenhum código de limitação é motivo contra o acesso.

• Sem contexto, toda avaliação é INCONCLUSIVE (acima).
• Com contexto, a avaliação só é COMPLETED quando pelo menos 30% dos 13 indicadores foram avaliados com evidência fresca (evidence_coverage ≥ 30) e os dois indicadores que contam para a nota, BOT_AUTOMATION e BROWSER_SPOOFING, foram avaliados.
• As regras ativas da sua empresa tornam obrigatório todo indicador que você ativa: um indicador ativo sem evidência fresca utilizável deixa a avaliação sem nota (trust_score: null, MONITOR), mesmo acima de 30% de cobertura (regras de risco).

Leia o not_evaluated_reason_code de cada indicador para ver o que faltou (códigos de limitação). Por exemplo:

• STALE_DEVICE_PROFILE: a evidência do navegador era mais antiga que a janela de evidência da sua aplicação (colete mais perto da ação), ou uma fonte de evidência do servidor era mais antiga que a sua idade máxima, o que coletar de novo não resolve.
• UNSUPPORTED_RUNTIME nos indicadores de privacidade do navegador e de navegação privada: o SDK rodou dentro de um iframe ou de um navegador embutido num app, ou não foi possível identificar o motor do navegador de forma consistente.
• REQUIRED_EVIDENCE_MISSING em DEVICE_MULTI_USER: esperado no primeiro login de uma nova instalação do navegador; os logins seguintes o avaliam.

Webhooks de saída

Os webhooks de saída de avaliação não estão habilitados (status em produção): não há webhook para configurar nem depurar. O seu backend recebe cada avaliação só na resposta ao seu POST /v1/assessments.

O que enviar ao suporte

Guarde e envie IDs de operação, request_id, correlation_id (o cabeçalho X-Correlation-Id de toda resposta), o assessment_id, códigos de erro públicos, horários e versões. Nunca envie tokens, segredos, cookies, cabeçalhos brutos, dados pessoais ou payloads completos.