Solução de problemas

Esta página lista os tipos de falha emitidos pelo SDK Web, problemas comuns de integração e os hosts que a sua página precisa liberar.

`LivenessFailureError`

Toda falha — reprovação biométrica ou erro técnico — chega via onFailure(error) e também rejeita a Promise do run():

interface LivenessFailureError {
  sessionId?: string;       // ausente se a falha foi antes de a sessão existir
  verified: false;
  type: LivenessErrorType;  // tabela abaixo
  failureReason?: string;   // motivo da reprovação em LIVENESS_FAILED; mensagem técnica nos demais
  nativeCode?: number;      // código técnico da tela de captura — útil para o suporte
  nativeType?: string;      // idem
}

{ "sessionId": "…", "verified": false, "type": "LIVENESS_FAILED", "failureReason": "SPOOF" }

Tipos de falha

Tipo	Causa	Ação recomendada
`LIVENESS_FAILED`	A captura foi analisada e reprovada — veja `failureReason`	Oferecer nova tentativa
`USER_CANCELLED`	O usuário fechou a tela	Oferecer nova tentativa
`CAPTURE_TIMEOUT`	Nenhum rosto capturado no tempo (`captureTimeout`)	Pedir para enquadrar o rosto e tentar de novo
`CAPTURE_FAILED`	Erro na tela de captura	Tentar de novo; se repetir, recarregar a página
`CAMERA_PERMISSION_DENIED`	Acesso à câmera negado	Orientar o usuário a liberar a câmera
`CAMERA_NOT_FOUND`	Nenhuma câmera no dispositivo	—
`BROWSER_NOT_SUPPORTED`	Navegador ou dispositivo sem suporte	Sugerir um navegador atualizado (Chrome, Edge, Safari ou Firefox)
`SESSION_FAILED`	`onInit` falhou, não devolveu `sessionId`/`sessionToken`, ou a sessão expirou	Verificar o seu backend; uma nova tentativa cria nova sessão
`NETWORK_ERROR`	Sem conexão com o servidor	Tentar de novo
`SUBMISSION_FAILED`	O servidor recusou o envio da captura	Tentar de novo; se persistir, contatar a equipe da Valid
`INITIALIZATION_FAILED`	Falha ao preparar a captura (ex.: rede) ou `run()` já em andamento	Tentar de novo
`UNKNOWN_ERROR`	Erro inesperado	Tentar de novo; reportar com `failureReason` e a versão do SDK

Motivos de reprovação

Em LIVENESS_FAILED, o failureReason indica o motivo:

Valor	Significado	Ação
`SPOOF`	Não foi possível confirmar uma pessoa real. Inclui ataques (foto de tela, impressa, máscara) e capturas ruins de pessoas reais (pouca luz, rosto coberto, desfoque)	Mensagem neutra, nunca acusatória: “Não conseguimos validar, tente de novo com boa iluminação e o rosto descoberto”. Muitas repetições seguidas podem indicar fraude
`INSECURE`	Câmera virtual ou vídeo injetado	Mensagem neutra; muitas repetições podem indicar fraude
`DEEPFAKE`	Rosto sintético	Mensagem neutra; muitas repetições podem indicar fraude
`QUALITY`	Imagem sem qualidade suficiente	Pedir mais luz e o rosto enquadrado, e tentar de novo
`EXPIRED`	A captura demorou demais para chegar ao servidor	Tentar de novo
`VENDOR_ERROR`	Erro interno na análise	Tentar de novo; se persistir, contatar a equipe da Valid

Exemplo de tratamento

function handleFailure(error) {
  switch (error.type) {
    case 'USER_CANCELLED':
      return; // retorno silencioso
    case 'CAMERA_PERMISSION_DENIED':
      mostrarMensagem('Permita o acesso à câmera nas configurações do navegador.');
      return;
    case 'BROWSER_NOT_SUPPORTED':
      mostrarMensagem('Atualize o navegador para continuar.');
      return;
    case 'LIVENESS_FAILED':
      if (error.failureReason === 'QUALITY') {
        mostrarMensagem('Procure um local bem iluminado e centralize o rosto.');
      } else {
        mostrarMensagem('Não conseguimos validar. Tente de novo com boa iluminação e o rosto descoberto.');
      }
      return;
    default:
      mostrarMensagem('Não foi possível concluir a verificação. Tente novamente.');
      console.error(error.type, error.failureReason, error.nativeCode, window.LivenessIdentySDK.SDK_VERSION);
  }
}

Problemas comuns

INITIALIZATION_FAILED com "HTTP 503 …" ou "network error (no HTTP response)"

O SDK não conseguiu se preparar (rede instável ou servidor indisponível). Uma nova chamada a run() refaz o processo, sem recarregar a página.

CAPTURE_FAILED em todas as tentativas

O motor de captura não carregou ou parou de funcionar na página. Recarregue a página. Se persistir, verifique a CSP (wasm-unsafe-eval, worker-src blob:) e o acesso a cdn.hub-liveness-service.app, e reporte à equipe da Valid com a versão do SDK.

A tela de captura aparece sem estilo

Os estilos não carregaram. Verifique style-src na CSP e o acesso à CDN (aba Network do DevTools).

run() fica parado em initializing

Algum recurso não respondeu. Verifique a rede e o connect-src da CSP; recarregar a página resolve.

A tela de instruções está em inglês

Ela é uma imagem. Troque por uma sua com graphics.FACE_TRAINING ou pule com showCaptureTraining: false. Veja Customização.

CAMERA_PERMISSION_DENIED sem o usuário negar

Página fora de HTTPS, câmera bloqueada pela política do site (Permissions-Policy: camera) ou iframe sem allow="camera".

A captura não funciona na minha página

Confirme que a origem exata da página (protocolo + domínio + porta) foi liberada pela equipe da Valid. Veja Autorize suas origens.

CSP e hosts de rede

Se a sua página usa Content Security Policy, inclua:

script-src   'self' https://cdn.hub-liveness-service.app 'wasm-unsafe-eval';
worker-src   blob:;
connect-src  https://cdn.hub-liveness-service.app https://identy.hub-liveness-service.app https://*.webdevicejs.com https://*.csftr.com https://*.ingest.us.sentry.io;
style-src    'self' https://cdn.hub-liveness-service.app 'unsafe-inline';
img-src      'self' https://cdn.hub-liveness-service.app data: blob:;
media-src    blob:;

Host	Motivo
`cdn.hub-liveness-service.app`	O script e seus arquivos (estilos, imagens, motor de captura)
`identy.hub-liveness-service.app`	Serviço de liveness
`.webdevicejs.com`, `.csftr.com`	Sinais do dispositivo
`*.ingest.us.sentry.io`	Opcional: diagnóstico de erros do SDK. Se bloqueado, o SDK funciona normalmente

Além desses, a página precisa acessar o seu próprio backend (o endpoint chamado no onInit).

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

`LivenessFailureError`

Tipos de falha

Motivos de reprovação

Exemplo de tratamento

Problemas comuns

CSP e hosts de rede

Próximos passos

Implementação

Customização

​LivenessFailureError

​Tipos de falha

​Motivos de reprovação

​Exemplo de tratamento

​Problemas comuns

​CSP e hosts de rede

​Próximos passos

Implementação

Customização

`LivenessFailureError`

Tipos de falha

Motivos de reprovação

Exemplo de tratamento

Problemas comuns

CSP e hosts de rede

Próximos passos