> ## 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 e diagnóstico do LivenessFacetecSDK Web v10

Esta página lista os tipos de erro emitidos pelo SDK Web v10, 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 {
  sessionId?: string;
  verified: false;
  type: LivenessErrorType;
  failureReason?: string;
  nativeType?: FaceTecNativeType;
}
```

| Campo           | Tipo                 | Descrição                                                                                                               |
| --------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `sessionId`     | `string?`            | ID da sessão em que o erro ocorreu, quando já existia uma sessão criada.                                                |
| `verified`      | `false`              | Sempre `false` em um `LivenessFailureError`.                                                                            |
| `type`          | `LivenessErrorType`  | Classificação unificada do erro — veja abaixo.                                                                          |
| `failureReason` | `string?`            | Mensagem complementar quando disponível.                                                                                |
| `nativeType`    | `FaceTecNativeType?` | Código nativo exato retornado pelo motor FaceTec, quando a falha se origina dele. Útil para reportar à equipe da Valid. |

## `LivenessErrorType`

`error.type` é um dos valores abaixo:

```typescript theme={"theme":"catppuccin-latte"}
enum LivenessErrorType {
  INITIALIZATION_FAILED,
  SESSION_FAILED,
  NETWORK_ERROR,
  CAPTURE_FAILED,
  SUBMISSION_FAILED,
  USER_CANCELLED,
  CAMERA_PERMISSION_DENIED,
  LOCKED_OUT,
  UNKNOWN_ERROR,
}
```

| Tipo                       | Quando acontece                                                                                 | Ação recomendada                                                                                      |
| -------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `INITIALIZATION_FAILED`    | Falha ao inicializar o motor FaceTec (domínio não autorizado, script vendor não carregou, etc.) | Verifique a lista de hosts liberados e o domínio autorizado. Se persistir, contate a equipe da Valid. |
| `SESSION_FAILED`           | Falha ao criar a sessão                                                                         | Revise a implementação do seu `onInit` e a resposta de `POST /api/v2/sessions`.                       |
| `CAMERA_PERMISSION_DENIED` | Usuário negou acesso à câmera                                                                   | Oriente a permitir nas configurações do navegador e tentar novamente.                                 |
| `USER_CANCELLED`           | Usuário cancelou o fluxo                                                                        | Ofereça um botão para tentar de novo — chame `sdk.run()` outra vez.                                   |
| `LOCKED_OUT`               | Dispositivo está em estado de bloqueio                                                          | Use `sdk.getLockoutEndTime()` para informar quando o usuário pode tentar novamente.                   |
| `SUBMISSION_FAILED`        | Falha ao submeter a captura                                                                     | Verifique conectividade do dispositivo do usuário.                                                    |
| `CAPTURE_FAILED`           | Erro durante a captura biométrica                                                               | Oriente sobre condições de câmera/ambiente e ofereça nova tentativa.                                  |
| `NETWORK_ERROR`            | Erro de rede                                                                                    | Verifique conectividade e a lista de hosts liberados.                                                 |
| `UNKNOWN_ERROR`            | Erro não identificado                                                                           | Reporte à equipe da Valid.                                                                            |

### Exemplo de tratamento

```javascript theme={"theme":"catppuccin-latte"}
const { LivenessErrorType } = window.LivenessFacetecSDK;

function handleFailure(error) {
  switch (error.type) {
    case LivenessErrorType.CAMERA_PERMISSION_DENIED:
      mostrarMensagem('Permita o acesso à câmera nas configurações do navegador.');
      return;
    case LivenessErrorType.USER_CANCELLED:
      return; // retorno silencioso
    case LivenessErrorType.LOCKED_OUT: {
      const until = sdk.getLockoutEndTime();
      mostrarMensagem(`Muitas tentativas. Tente novamente às ${new Date(until).toLocaleTimeString()}.`);
      return;
    }
    default:
      mostrarMensagem('Não foi possível concluir a verificação. Tente novamente.');
      console.error(error.type, error.nativeType, error.failureReason);
  }
}
```

## Erros comuns de console

| Sintoma                                                                      | Causa provável                                                                                                                                                       |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FaceTecSDK is not defined`                                                  | O bundle do motor FaceTec não carregou a partir do CDN. Verifique se `cdn.hub-liveness-service.app` está acessível pela página.                                      |
| Falha no handshake de inicialização (erro reportado antes de abrir a câmera) | O domínio da sua aplicação não está autorizado na licença FaceTec, ou há um erro de configuração no lado do backend. Contate a equipe da Valid informando o domínio. |

## Hosts de rede necessários

A página que carrega o SDK precisa conseguir acessar:

* `cdn.hub-liveness-service.app` — bundle do SDK e assets do motor FaceTec.
* `api.valid.com` — serviço FaceTec.
* O seu próprio backend (endpoint que chama `POST /api/v2/sessions`).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/implementacao">
    Configuração completa e fluxo de captura
  </Card>

  <Card title="Customização" icon="palette" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/customizacao">
    Locales, textos e tema visual da UI
  </Card>
</CardGroup>