> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/android/error-handling.md).

# Tratamento de erros

Quando o processo de liveness não pode ser concluído, o SDK retorna um `LivenessLiteEvent.Error` evento. Esse evento contém um `parâmetro` parâmetro, um `CafLivenessErrorType` enum que informa por que o processo foi interrompido.

Erros são diferentes de falhas:

* Uma **falha** (`LivenessLiteEvent.Failure`) significa que a captura foi executada, mas o usuário não foi aprovado na verificação. Sempre carrega uma resposta assinada. Veja [Razões da falha e orientações para o usuário](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/handling-failures.md).
* Um **erro** (`LivenessLiteEvent.Error`) significa que um problema técnico impediu o SDK de iniciar ou concluir o processo. Nenhuma captura foi avaliada, então não há resposta assinada.

## O Modelo de Erro

{% code title="LivenessLiteEvent.kt" lineNumbers="true" %}

```kotlin
public sealed interface LivenessLiteEvent {
    data class pública Error(
        val type: CafLivenessErrorType,
        val description: String,
        val cause: Throwable
    ) : LivenessLiteEvent
}
```

{% endcode %}

| Parâmetro     | Descrição                                                                        |
| ------------- | -------------------------------------------------------------------------------- |
| `parâmetro`   | A categoria do erro. Use-a para decidir o que exibir e se deve tentar novamente. |
| `description` | Uma mensagem técnica em inglês. Use-a em logs, não para os usuários finais.      |
| `causa`       | A exceção original. Envie-a para sua ferramenta de relatório de falhas ou erros. |

{% hint style="info" %}
Um erro sempre encerra a execução do liveness. Você pode chamar `startLiveness()` novamente logo após recebê-lo.
{% endhint %}

### Usando o `parâmetro` Parâmetro

Boa prática: não exiba o nome bruto do enum nem o `description` para os usuários finais. Mapeie o `parâmetro` para uma mensagem localizada no seu app e registre o `description` e `causa` para que sua equipe possa investigar.

Na maioria dos casos, o usuário não consegue resolver um erro mudando a forma como faz a captura. As exceções são a permissão da câmera e a conexão. Outros erros apontam para um problema de integração, como uma `configure()` chamada ausente, e devem ser corrigidos na configuração do seu app ou da sua conta.

{% hint style="warning" %}
Nunca diga ao usuário qual verificação de segurança falhou, nem mostre detalhes técnicos como dados de certificado, endereços internos ou rastreamentos de pilha. Essas informações ajudam quem está tentando burlar a jornada.
{% endhint %}

### Tipos de Erro em Resumo

| Tipo                      | Categoria  | Causa típica                                                   | Mensagem recomendada                                     |
| ------------------------- | ---------- | -------------------------------------------------------------- | -------------------------------------------------------- |
| `CONFIGURATION_EXCEPTION` | Integração | O SDK foi iniciado sem a configuração necessária.              | Não conseguimos concluir a verificação.                  |
| `TOKEN_EXCEPTION`         | Integração | O `mobileToken` não está configurado para o fluxo de liveness. | Não conseguimos concluir a verificação. Tente novamente. |
| `CAMERA_PERMISSION`       | Usuário    | O acesso à câmera foi negado.                                  | Permita o acesso à câmera para continuar.                |
| `NETWORK_EXCEPTION`       | Ambiente   | A sessão não pôde ser criada, ou a conexão caiu.               | Sem conexão. Verifique sua internet e tente novamente.   |
| `SERVER_EXCEPTION`        | Ambiente   | O servidor do provedor de liveness retornou um erro.           | Não conseguimos concluir a verificação. Tente novamente. |
| `SECURITY_EXCEPTION`      | Ambiente   | Uma ou mais verificações de segurança do ambiente falharam.    | Não conseguimos concluir a verificação. Tente novamente. |
| `UNSUPPORTED_DEVICE`      | Ambiente   | O dispositivo não atende aos requisitos de captura.            | Não conseguimos concluir a verificação.                  |
| `GENERIC_EXCEPTION`       | Outro      | Um erro inesperado sem causa conhecida.                        | Não conseguimos concluir a verificação. Tente novamente. |
| `LIVENESS_EXCEPTION`      | Outro      | Reservado. Não é retornado atualmente.                         | Não conseguimos concluir a verificação. Tente novamente. |

## Erros de integração

Esses erros geralmente apontam para um problema na integração entre seu app e o SDK, não para algo que o usuário possa resolver.

### `CONFIGURATION_EXCEPTION`

O SDK foi iniciado sem a configuração necessária para abrir a verificação. Isso acontece em três casos:

* `startLiveness()` foi chamado antes de `configure()`.
* `mobileToken` ou `personId` está vazio ou em branco.
* `startLiveness()` foi chamada enquanto outra execução de liveness ainda estava ativa.

**Mensagem recomendada:** *Não conseguimos concluir a verificação.*

**O que fazer:** não ofereça uma nova tentativa. Encaminhe o usuário para o suporte ou para outro canal. No seu app, chame `CafFaceLivenessLite.instance.configure(context, config)` com um válido `mobileToken` e `personId` antes de `startLiveness()`, e aguarde a execução atual retornar um evento final antes de iniciar uma nova.

{% hint style="info" %}
Uma nova tentativa não altera o resultado. Esse erro não deve ser frequente em produção, então monitore-o e configure um alerta quando ele acontecer. Use o `description` para diferenciar os três casos nos seus logs.
{% endhint %}

### `TOKEN_EXCEPTION`

O `mobileToken` não está configurado para o fluxo de liveness, então a sessão não pôde ser criada. Causas comuns:

* O provedor de liveness não está habilitado para a conta ou para a configuração do token.
* A sessão retornada pelo servidor estava incompleta, por exemplo sem o identificador da tentativa ou a resposta assinada.

**Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.*

**O que fazer:** ofereça uma nova tentativa com um novo token. Se o erro persistir com tokens novos, verifique a configuração do token com a Certta.

{% hint style="info" %}
Crie o token imediatamente antes de abrir o SDK e crie um novo para cada nova tentativa.
{% endhint %}

## Erros de usuário e ambiente

Esses erros dependem do usuário, do dispositivo ou da rede. Exiba uma mensagem útil e permita que o usuário tente novamente quando fizer sentido.

### `CAMERA_PERMISSION`

O acesso à câmera foi negado, e o SDK não pode iniciar a captura. Causas comuns:

* O usuário negou o acesso quando foi solicitada a permissão.
* A permissão foi negada antes. Após algumas recusas, o sistema pode não perguntar novamente.
* Uma permissão de uso único já expirou.
* A permissão foi revogada nas configurações ou bloqueada por restrições do dispositivo, como controle dos pais ou gerenciamento corporativo do dispositivo.

**Mensagem recomendada:** *Permita o acesso à câmera para continuar.*

**O que fazer:** mostre uma tela específica com um botão que abre as configurações do app.

{% hint style="info" %}
Como o sistema pode não exibir a solicitação de permissão novamente, o botão deve abrir diretamente as configurações do app em vez de apenas tentar de novo.
{% endhint %}

### `NETWORK_EXCEPTION`

O SDK não pôde criar a sessão de liveness, ou a conexão caiu durante a captura. Causas comuns:

* Sem internet, ou modo avião ativado.
* Sinal fraco ou instável, como em um elevador, no metrô ou em um porão.
* A rede mudou durante a verificação.
* Um Wi-Fi público que exige login, mas ele ainda não foi feito.
* Uma VPN, proxy ou firewall bloqueando os serviços usados pelo SDK.
* Uma falha na validação do certificado de segurança da conexão, causada por um antivírus ou proxy que inspeciona o tráfego, por uma rede corporativa que intercepta o tráfego ou por data e hora incorretas no dispositivo.
* Os serviços da Certta responderam à solicitação da sessão com um erro HTTP, por exemplo devido a um token expirado ou a um token de outro ambiente.

**Mensagem recomendada:** *Sem conexão. Verifique sua internet e tente novamente.*

**O que fazer:** mostre uma tela de conexão com um botão para tentar novamente.

{% hint style="info" %}
Crie o token logo antes de abrir o SDK e crie um novo para cada nova tentativa. Isso evita erros HTTP causados por tokens expirados.
{% endhint %}

### `SERVER_EXCEPTION`

O servidor do provedor de liveness retornou um erro durante a captura. Causas comuns:

* Instabilidade momentânea ou indisponibilidade dos serviços do provedor.
* A sessão de liveness foi invalidada no servidor.

**Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.*

**O que fazer:** deixe o usuário tentar novamente.

{% hint style="warning" %}
A mensagem técnica desse erro pode conter detalhes de certificado, endereços internos ou stack traces. Nunca a mostre ao usuário.
{% endhint %}

### `SECURITY_EXCEPTION`

`enableSecurity` é `true`, e uma ou mais verificações de segurança do ambiente falharam antes ou durante a captura. O SDK bloqueou a captura para proteger a jornada. Causas comuns:

* Um dispositivo com root, incluindo Magisk ou Zygisk.
* Frameworks de hooking, como Frida, Xposed ou LSPosed.
* Bibliotecas de hooking ou injeção carregadas no app, ou funções do sistema redirecionadas ou alteradas em tempo de execução.
* Um depurador anexado ao app, um processo rastreando o app ou um app compilado como debuggable.
* Um conflito entre a proteção do próprio app e o módulo de segurança do SDK.
* Uma verificação de segurança que não pôde ser executada. O SDK a trata como uma ameaça.

**Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.*

**O que fazer:** deixe o usuário tentar novamente, com uma mensagem genérica. A detecção é salva no dispositivo, então o mesmo dispositivo retorna o mesmo erro até que os dados do app sejam apagados ou o app seja reinstalado. Se continuar acontecendo, encaminhe o usuário para outro fluxo de verificação. Veja [Verificações de segurança](/sdk-lite/sdk-lite-english-pt-br/configuracao/android/security-checks.md).

{% hint style="warning" %}
Nunca diga ao usuário qual verificação falhou, porque isso ensina como contornar a proteção. Se o volume for relevante entre usuários legítimos, analise os logs junto com a Certta.
{% endhint %}

### `UNSUPPORTED_DEVICE`

O dispositivo não atende aos requisitos mínimos de hardware ou sistema para a captura. Causas comuns:

* Sem câmera frontal.
* Recursos de hardware exigidos pela captura estão ausentes, o que é comum em dispositivos muito antigos.

**Mensagem recomendada:** *Não conseguimos concluir a verificação.*

**O que fazer:** não ofereça uma nova tentativa. Encaminhe o usuário para o suporte ou para outro canal.

## Outros erros

### `GENERIC_EXCEPTION`

Um erro inesperado do SDK que não se encaixa em nenhum dos casos acima. Causas comuns:

* O app está em modo de tela dividida ou multi-janela.
* A câmera não pôde ser aberta ou falhou durante a captura, por exemplo porque outro app está usando-a.
* Uma exceção inesperada durante o fluxo de liveness.

**Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.*

**O que fazer:** deixe o usuário tentar novamente.

{% hint style="info" %}
Para esses casos, o log técnico é essencial. Registre o tipo, o `description`, a versão do SDK, o modelo do dispositivo e a versão do Android, e compartilhe-os com a Certta para que o caso possa ser mapeado.
{% endhint %}

### `LIVENESS_EXCEPTION`

Reservado para uso futuro. O Face Liveness Lite não retorna esse tipo hoje.

**O que fazer:** trate-o como `GENERIC_EXCEPTION`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/android/error-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.