Solução de problemas

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

Cheque a versão carregada

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

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/...

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.

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

Logs detalhados

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

`LivenessFailureError`

`LivenessErrorType`

Exemplo de tratamento

Estados do SDK

Problemas comuns

`window.LivenessFacetecSDK` é `undefined`

`Refused to load the script` (CSP)

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

`CORS` ao chamar o backend a partir do onInit

`SESSION_FAILED` logo no início

Captura passa, mas resultado vem `verified: false`

Verificação de saúde

Próximos passos

Implementação

Customização

​LivenessFailureError

​LivenessErrorType

​Exemplo de tratamento

​Estados do SDK

​Problemas comuns

​window.LivenessFacetecSDK é undefined

​Refused to load the script (CSP)

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

​CORS ao chamar o backend a partir do onInit

​SESSION_FAILED logo no início

​Captura passa, mas resultado vem verified: false

​Verificação de saúde

​Próximos passos

Implementação

Customização

`LivenessFailureError`

`LivenessErrorType`

Exemplo de tratamento

Estados do SDK

Problemas comuns

`window.LivenessFacetecSDK` é `undefined`

`Refused to load the script` (CSP)

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

`CORS` ao chamar o backend a partir do onInit

`SESSION_FAILED` logo no início

Captura passa, mas resultado vem `verified: false`

Verificação de saúde

Próximos passos