> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de problemas

> Mapeamento de erros, CSP e diagnóstico do LivenessIdentySDK Web

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()`:

```typescript theme={"theme":"catppuccin-latte"}
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
}
```

```json theme={"theme":"catppuccin-latte"}
{ "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`](#motivos-de-reprovação) | 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

```javascript theme={"theme":"catppuccin-latte"}
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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/customizacao.md#visual).

> **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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/instalacao.md#autorize-suas-origens).

## CSP e hosts de rede

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

```text theme={"theme":"catppuccin-latte"}
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`).

## Próximos passos

> **[Implementação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/implementacao.md)**
>
> Configuração completa e fluxo de captura

> **[Customização](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/customizacao.md)**
>
> Idioma, segurança, captura e visual da tela


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.