Solução de problemas

Hierarquia de erros e diagnóstico do LivenessFacetecSDK Web

Esta página lista os tipos de erro emitidos pelo SDK Web, problemas comuns de integração e dicas de diagnóstico.

LivenessFailureError

Toda falha técnica chega via onFailure(error: LivenessFailureError):

interface LivenessFailureError {
  type: LivenessErrorType;
  failureReason?: string;
  attemptsLeft?: number;
}

Campo	Tipo	Descrição
type	LivenessErrorType	Classificação do erro.
failureReason	string?	Mensagem complementar quando disponível.
attemptsLeft	number?	Tentativas restantes quando a sessão foi encerrada por falha definitiva (esgotamento de tentativas ou fraude detectada).

LivenessErrorType

error.type é um dos valores abaixo:

enum LivenessErrorType {
  INITIALIZATION_FAILED = 'INITIALIZATION_FAILED',
  SESSION_FAILED = 'SESSION_FAILED',
  CAPTURE_FAILED = 'CAPTURE_FAILED',
  LIVENESS_VALIDATION_FAILED = 'LIVENESS_VALIDATION_FAILED',
  SUBMISSION_FAILED = 'SUBMISSION_FAILED',
  CAMERA_PERMISSION_DENIED = 'CAMERA_PERMISSION_DENIED',
  USER_CANCELLED = 'USER_CANCELLED',
  NETWORK_ERROR = 'NETWORK_ERROR',
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
}

Tipo	Quando acontece	Ação recomendada
INITIALIZATION_FAILED	Falha ao carregar o vendor FaceTec ou inicializar o motor	Verifique CSP / bloqueio de *.googleapis.com. Cheque conectividade.
SESSION_FAILED	O seu backend (via onInit) retornou erro ou tokens inválidos	Verifique sua x-api-key. Confirme que o backend está respondendo 200 com sessionId, sessionToken e facetecSessionToken.
CAPTURE_FAILED	A captura biométrica do FaceTec falhou (timeout, qualidade insuficiente, erro do motor)	Apresente UI de “tentar novamente”. failureReason traz o motivo do FaceTec.
LIVENESS_VALIDATION_FAILED	A captura foi submetida, mas o backend reprovou o liveness	Não é erro técnico; é reprovação biométrica. Trate como negativa de verificação.
SUBMISSION_FAILED	Falha ao submeter a captura ao backend	Reverifique CORS, conectividade e validade dos tokens.
CAMERA_PERMISSION_DENIED	Usuário negou acesso à câmera	Oriente a permitir nas configurações do navegador e recarregar.
USER_CANCELLED	Usuário fechou a UI do FaceTec	Retorno silencioso para a tela anterior; geralmente não é erro de UX.
NETWORK_ERROR	Sem conectividade ou timeout HTTP	Oriente a verificar a rede. O SDK não tenta retry automático.
UNKNOWN_ERROR	Exceção não mapeada	Capture failureReason e reporte à equipe da Valid.

Exemplo de tratamento

const { LivenessErrorType } = window.LivenessFacetecSDK;

function handleFailure(error) {
  switch (error.type) {
    case LivenessErrorType.LIVENESS_VALIDATION_FAILED:
      mostrarMensagem('A verificação não foi aprovada. Vamos tentar outra vez?');
      return;
    case LivenessErrorType.CAMERA_PERMISSION_DENIED:
      mostrarMensagem('Permita o acesso à câmera nas configurações do navegador.');
      return;
    case LivenessErrorType.NETWORK_ERROR:
      mostrarMensagem('Sem conexão com a internet.');
      return;
    case LivenessErrorType.USER_CANCELLED:
      return;
    default:
      mostrarMensagem(`Erro: ${error.type}${error.failureReason ? ` — ${error.failureReason}` : ''}`);
  }
}

Estados do SDK

onProgress(state: HubState) permite acompanhar o ciclo de vida visual:

enum HubState {
  Uninitialized = 'uninitialized',
  Initializing = 'initializing',
  Ready = 'ready',
  Capturing = 'capturing',
  Closing = 'closing',
  Error = 'error',
}

Use para mostrar/ocultar spinners, habilitar botões, ou enviar telemetria.

Problemas comuns

window.LivenessFacetecSDK é undefined

O script do CDN não carregou ou está sendo executado antes do <script> do SDK. Confira:

• A tag <script> aparece antes do código que usa window.LivenessFacetecSDK.
• O domínio cdn.hub-liveness-service.app está acessível (não bloqueado por proxy/CSP).

Refused to load the script (CSP)

Sua política de segurança bloqueou o CDN ou o bucket do vendor. Permita:

script-src https://cdn.hub-liveness-service.app https://storage.googleapis.com;
connect-src https://facetec.hub-liveness-service.app https://*.fpjs.io;
img-src https://storage.googleapis.com data:;
worker-src 'self' blob:;

Câmera não aparece, sem prompt de permissão

A página precisa rodar em contexto seguro (https:// ou localhost). Em http:// (com host diferente de localhost), getUserMedia é silenciosamente desabilitado e o SDK aborta com CAMERA_PERMISSION_DENIED sem mostrar a UI nativa do browser.

CORS ao chamar o backend a partir do onInit

O fetch do onInit parte do navegador para o seu backend — não para a Plataforma ID. Configure CORS no seu endpoint para aceitar o origin onde a página está hospedada.

SESSION_FAILED logo no início

Geralmente é o onInit rejeitando ou retornando um payload inválido. Confirme:

• O endpoint do seu backend devolve exatamente { sessionId, sessionToken, facetecSessionToken } (não devolva a x-api-key, não devolva campos extras desnecessários).
• O status HTTP é 2xx.
• A x-api-key que o backend usa está válida — veja Serviço.

Captura passa, mas resultado vem verified: false

Não é erro técnico. O backend reprovou o liveness (livenessCheck = false). Trate como negativa de verificação: mostre mensagem ao usuário e ofereça nova tentativa. Os campos *Check indicam qual validação falhou.

Verificação de saúde

1. Cheque a versão carregada

   console.log(window.LivenessFacetecSDK.SDK_VERSION) — confirma que o bundle foi avaliado.

2. Confirme o backend embutido

   Abra DevTools → Network e dispare uma captura. A request de criação de sessão deve sair para https://facetec.hub-liveness-service.app/...

3. Valide o onInit

   Imprima o retorno do seu onInit antes de devolver — o objeto deve ter exatamente sessionId, sessionToken e facetecSessionToken como strings não vazias.

4. Confirme conectividade com o vendor

   Em DevTools → Network, deve aparecer um GET a https://storage.googleapis.com/public-hub-liveness/core-sdk/... (vendor FaceTec sendo carregado).

5. Logs detalhados

   Filtre o console por [FaceTecSDK] ou [Hub] para inspecionar a sequência de inicialização.

Próximos passos

Implementação

Volte para a referência de uso do SDK

Customização

Veja como personalizar a UI