> ## 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

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

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

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

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

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

```text theme={"theme":"catppuccin-latte"}
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](/plataforma/liveness/facetec/servico).

### 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

<Steps>
  <Step title="Cheque a versão carregada">
    `console.log(window.LivenessFacetecSDK.SDK_VERSION)` — confirma que o bundle foi avaliado.
  </Step>

  <Step title="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/...`
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Logs detalhados">
    Filtre o console por `[FaceTecSDK]` ou `[Hub]` para inspecionar a sequência de inicialização.
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" href="/plataforma/liveness/facetec/sdk/web/implementacao">
    Volte para a referência de uso do SDK
  </Card>

  <Card title="Customização" icon="palette" href="/plataforma/liveness/facetec/sdk/web/customizacao">
    Veja como personalizar a UI
  </Card>
</CardGroup>