> 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-falhas/mobile/failure-handling.md).

# Razões da falha e orientações para o usuário

Quando a captura chega ao fim, mas não é aprovada, o SDK retorna um `Failure` evento. Seu `type` parâmetro, um `CafFailureType` enum, indica o motivo mais provável, para que você possa orientar o usuário a ter sucesso na próxima tentativa.

A maioria das falhas pode ser resolvida pelo usuário com boas orientações sobre iluminação, distância, posição e estabilidade.

{% hint style="info" %}
Algumas situações comuns não são falhas. Acesso à câmera negado, uma conexão que cai, um serviço indisponível ou um token expirado interrompem a execução antes que qualquer captura seja avaliada. Por isso, o SDK retorna um erro, e não uma falha, sem resposta assinada. Consulte [Tratamento de erros no Android](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/android/error-handling.md) e [Tratamento de erros no iOS](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios/error-handling.md).
{% endhint %}

## A estrutura de Failure

{% tabs %}
{% tab title="Android" %}

```kotlin
public sealed interface LivenessLiteEvent {

    public data class Failure(
        val signedResponse: String,
        val type: CafFailureType,
        val description: String,
    ) : LivenessLiteEvent
}
```

{% endtab %}

{% tab title="iOS" %}

```swift
public protocol CafFaceLivenessLiteDelegate: AnyObject {
    // ...
    func didFinishWithFailure(type: CafFailureType, description: String?, signedResponse: String?)
}
```

{% endtab %}
{% endtabs %}

| Parâmetro        | Descrição                                                                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signedResponse` | O resultado assinado pelo servidor. Envie-o ao seu back-end, assim como faria com um resultado de sucesso.                                                                                |
| `type`           | O motivo mais provável da falha. Use-o para escolher a mensagem destinada ao usuário.                                                                                                     |
| `description`    | Uma mensagem da análise de vivacidade, destinada aos seus logs. Ela pode estar no idioma do dispositivo e talvez não corresponda à mensagem recomendada. Não a exiba aos usuários finais. |

{% hint style="warning" %}
Nunca determine o resultado no dispositivo. Seu back-end valida a resposta assinada (a assinatura e o `tokenId`) e, em seguida, recupera o resultado final, incluindo `isAlive`, com o `livenessAttemptId` que ela contém. Consulte [Configuração do back-end](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md).
{% endhint %}

### Como interpretar o `type`

A análise de vivacidade é feita por um modelo de inteligência artificial. Ele avalia a captura e atribui a cada falha seu motivo **mais provável** . Essa classificação é probabilística: o modelo pode retornar um motivo que não pareça corresponder ao que aconteceu. Por exemplo, pode indicar excesso de iluminação em um ambiente que parece normalmente iluminado ou uso de óculos por uma pessoa que não está usando óculos.

Considere o `type` como uma indicação da causa mais provável, não como uma descrição exata do que aconteceu. As causas listadas nesta página são as mais comumente associadas a cada tipo, mas não há garantia de que sejam a causa real em uma sessão específica.

Quando a análise suspeita que a captura não mostra uma pessoa real diante da câmera, o serviço de vivacidade retorna orientações genéricas de propósito, para não revelar o que foi detectado. Nesses casos, tipos como `MOTION_ISSUE` e `DEVICE_ISSUE` pode não refletir a causa real. Esse é mais um motivo para manter as mensagens neutras e tratar falhas repetidas como um padrão a ser investigado, não como um erro do usuário.

{% hint style="info" %}
A `description` pode sugerir algo diferente da mensagem recomendada. Por exemplo, a `description` de um problema de movimento pode pedir que o usuário tente usar outro dispositivo. Sempre exiba a mensagem recomendada para o `type`, e sugira outro dispositivo apenas como alternativa, após várias tentativas.
{% endhint %}

### Regras para todas as mensagens

1. **Oriente a próxima tentativa.** Durante a captura, a tela de captura já exibe instruções em tempo real, como "Aproxime-se" ou "Não se mova". As mensagens desta página são exibidas após uma tentativa malsucedida e, por isso, dizem o que fazer na próxima tentativa.
2. **Segurança acima da especificidade.** Nunca informe ao usuário que há suspeita de fraude, qual verificação de segurança falhou ou se uma face está cadastrada para alguém. Essas informações ajudam quem está tentando burlar o fluxo.
3. **Tom neutro.** As mensagens descrevem o que fazer, sem dizer o que a pessoa fez de errado. A análise do modelo pode estar errada, e uma mensagem acusatória piora a experiência de usuários legítimos.

{% hint style="info" %}
As mensagens recomendadas nesta página vêm de um estudo da equipe de UX da Certta. O estudo considerou clareza, linguagem neutra, acessibilidade e segurança do fluxo.
{% endhint %}

### Referência rápida

Os tipos de falha são os mesmos nas duas plataformas, mas têm grafias diferentes. A tabela mostra ambas. A coluna **Imagem do resultado** indica se o backend pode esperar uma imagem ao recuperar o resultado da tentativa.

A tabela lista apenas os tipos retornados pelas versões atuais. Os tipos antigos que não são mais retornados, como `TOO_DARK` ou `FACE_TOO_FAR`, estão em [Tipos legados](#legacy-types).

<table><thead><tr><th width="184.921875">Android</th><th>iOS</th><th>Motivo</th><th>Mensagem recomendada</th><th>Imagem do resultado</th></tr></thead><tbody><tr><td><code>UNKNOWN</code></td><td><code>unknown</code></td><td>Falha não classificada</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Geralmente disponível</td></tr><tr><td><code>LIGHTING_ISSUES</code></td><td><code>lightingIssues</code></td><td>Iluminação inadequada</td><td>Verifique se seu rosto está bem iluminado e sem reflexos.</td><td>Disponível</td></tr><tr><td><code>FACE_NOT_FOUND</code></td><td><code>faceNotFound</code></td><td>Posição do rosto no guia</td><td>Mantenha a câmera frontal na altura dos olhos.</td><td>Não disponível</td></tr><tr><td><code>EYES_CLOSED</code>, <code>EYEWEAR</code></td><td><code>eyesClosed</code>, <code>eyewear</code></td><td>Área dos olhos não confirmada</td><td>Verifique se seus olhos estão visíveis.</td><td>Disponível</td></tr><tr><td><code>OBSCURED_FACE</code></td><td><code>obscuredFace</code></td><td>Rosto coberto</td><td>Certifique-se de que seu rosto esteja totalmente visível e remova qualquer acessório que possa cobri-lo.</td><td>Disponível</td></tr><tr><td><code>MULTIPLE_FACES</code></td><td><code>multipleFaces</code></td><td>Mais de um rosto</td><td>Certifique-se de que apenas seu rosto apareça na tela.</td><td>Disponível</td></tr><tr><td><code>FRAMES_BLURRY</code></td><td><code>framesBlurry</code></td><td>Imagem desfocada</td><td>Procure um local bem iluminado, limpe a câmera frontal e mantenha o celular firme.</td><td>Disponível</td></tr><tr><td><code>MOTION_ISSUE</code></td><td><code>motionIssue</code></td><td>Movimento inconsistente</td><td>Mantenha o celular parado, na altura dos olhos, e posicione seu rosto dentro do oval.</td><td>Disponível</td></tr><tr><td><code>BACKGROUND_ISSUE</code></td><td><code>backgroundIssue</code></td><td>Fundo ou contraste</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Disponível</td></tr><tr><td><code>DEVICE_ISSUE</code></td><td><code>deviceIssue</code></td><td>Dispositivo ou ambiente</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Disponível</td></tr><tr><td><code>DEVICE_RESTART</code></td><td><code>deviceRestart</code></td><td>Reinicialização do dispositivo</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Disponível</td></tr><tr><td><code>SYSTEM_ERROR</code></td><td><code>systemError</code></td><td>Erro do sistema</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Disponível</td></tr><tr><td><code>USER_NOT_FOUND</code></td><td><code>userNotFound</code></td><td>Usuário não cadastrado</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Disponível</td></tr><tr><td><code>REJECTED</code></td><td><code>rejected</code></td><td>Transação rejeitada</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Disponível</td></tr><tr><td><code>TIMEOUT</code></td><td><code>timeout</code></td><td>Tempo limite atingido</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Disponível</td></tr><tr><td><code>PROCESSING_FAULT</code></td><td><code>processingFault</code></td><td>Falha no processamento</td><td>Não foi possível concluir a verificação. Tente novamente.</td><td>Não disponível</td></tr></tbody></table>

### Falha não classificada

`UNKNOWN`

**O que significa:** a sessão terminou sem aprovação, mas não foi possível atribuir um motivo específico à análise. Este é um resultado abrangente: algo impediu uma decisão segura, mas não é possível dizer o quê.

**Causas comuns:**

* Vários pequenos fatores ao mesmo tempo (um pouco de movimento, iluminação irregular, rosto ligeiramente fora do centro).
* Um resultado ambíguo, em que a análise não reuniu evidências suficientes para decidir.
* Dispositivos antigos ou básicos, com câmeras de qualidade inferior.
* Bloqueios de prevenção contra fraudes.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** uma nova tentativa.

**Tentar novamente:** sim. Se o problema continuar acontecendo, entre em contato com o suporte da Certta.

{% hint style="warning" %}
Uma `UNKNOWN` falha pode não retornar uma imagem do resultado. Quando seu back-end recuperar o resultado desta tentativa, talvez a imagem não esteja disponível. Por isso, qualquer etapa que dependa dela, como a correspondência facial ou o salvamento de uma foto de referência, pode não ser executada. Verifique se a imagem está disponível antes de usá-la e solicite uma nova captura ao usuário.
{% endhint %}

{% hint style="warning" %}
Como a causa real é desconhecida, evite dar dicas específicas aqui. Orientações incorretas, como "procure um lugar mais iluminado" quando o problema foi movimento, tendem a causar novas falhas e frustração. Além disso, como esse tipo também pode representar um bloqueio de segurança, a mensagem não deve sugerir nenhum motivo.
{% endhint %}

### Iluminação inadequada

`LIGHTING_ISSUES`

**O que significa:** a iluminação atrapalhou a análise, mas o resultado não informa se havia luz demais ou de menos. Geralmente, isso envolve luz forte no rosto, um ambiente escuro, iluminação desigual, sombras ou reflexos.

**Causas comuns:**

* Luz forte direcionada diretamente ao rosto, como a de uma lanterna, uma lâmpada ou a luz solar direta.
* Uma janela muito iluminada ou uma luz forte atrás do usuário.
* Um ambiente mal iluminado.
* Luz vindo de apenas um lado, deixando metade do rosto na sombra.
* Reflexos fortes na pele ou nos óculos.
* Acessórios que cobrem parte do rosto e projetam sombras ou reflexos sobre ele, como um headset ou um boné.
* Luzes coloridas no ambiente (LED, TV, letreiros).
* A iluminação muda durante a captura.

Em um ambiente completamente escuro, a captura não é iniciada.

**Mensagem recomendada:** *Verifique se seu rosto está bem iluminado e sem reflexos.*

**Comportamento:** dica exibida após a tentativa.

**Tentar novamente:** sim. Permita que o usuário tente novamente.

{% hint style="info" %}
A mensagem não diz para aumentar ou diminuir a iluminação de propósito, pois esse tipo não informa qual das duas opções se aplica.
{% endhint %}

### Posição do rosto na moldura-guia

`FACE_NOT_FOUND`

**O que significa:** nenhum rosto foi detectado na área de captura no momento da captura.

**Causas comuns:**

* O rosto sai do oval pouco antes da captura.
* O celular está abaixo do nível do queixo.
* O rosto está inclinado, de perfil ou deslocado para um dos lados do oval.
* O usuário olha para outro ponto da tela.
* A câmera está apontada para outro lugar ou a captura foi iniciada antes de o usuário se posicionar.
* Um ambiente escuro combinado com um dispositivo tremendo.
* A lente está coberta por um dedo, uma capa ou sujeira.

**Mensagem recomendada:** *Mantenha a câmera frontal na altura dos olhos.*

**Comportamento:** dica exibida após a tentativa.

**Tentar novamente:** sim. Permita que o usuário tente novamente.

{% hint style="info" %}
Um `FACE_NOT_FOUND` não retorna uma imagem do resultado. Quando seu back-end recuperar o resultado desta tentativa, nenhuma imagem estará disponível. Por isso, qualquer etapa que dependa dela, como a correspondência facial ou o salvamento de uma foto de referência, não poderá ser executada. Considere que esta tentativa não tem uma imagem e solicite uma nova captura ao usuário.
{% endhint %}

### Área dos olhos não confirmada

`EYES_CLOSED` `EYEWEAR`

**O que significa:** a análise não conseguiu confirmar a área dos olhos. Na prática, os dois tipos levam à mesma situação: os olhos não estavam visíveis com clareza suficiente.

**Causas comuns:**

* Óculos escuros, a causa mais consistente de `EYEWEAR`.
* Piscar no momento da captura.
* Apertando os olhos por causa da luz.
* Olhando para baixo.
* Maquiagem pesada nos olhos.
* Uma mão perto do rosto.
* Acessórios que cobrem parte do rosto perto dos olhos, como um headset, a aba de um boné ou um capuz.

Óculos de grau geralmente não causam essa falha. Ela também pode ocorrer sem óculos e com os olhos abertos, por causa de uma sombra ou reflexo ao redor dos olhos, do ângulo do celular ou de uma imagem desfocada.

**Mensagem recomendada:** *Certifique-se de que seus olhos estejam visíveis.*

**Comportamento:** dica neutra exibida após a tentativa.

**Tentar novamente:** sim. Permita que o usuário tente novamente.

{% hint style="warning" %}
A mensagem é neutra de propósito. Ela não diz "seus olhos estavam fechados" nem "tire os óculos", porque a leitura pode estar errada. Uma mensagem acusatória para alguém que não está usando óculos causa constrangimento e dá a impressão de que o sistema cometeu um erro.
{% endhint %}

### Rosto coberto

`OBSCURED_FACE`

**O que significa:** parte do rosto foi coberta por um objeto, o que impediu uma análise completa.

**Causas comuns:**

* Uma máscara, um cachecol ou uma gola alta cobrindo a boca e o queixo.
* Acessórios que cobrem parte do rosto, como um headset com microfone diante da boca.
* Uma mão tocando o rosto.
* Cabelo ou franja sobre os olhos.
* Um boné, chapéu ou capuz cobrindo a testa.
* Um dedo ou uma capinha cobrindo parte da lente.

**Mensagem recomendada:** *Certifique-se de que seu rosto inteiro esteja visível e retire os acessórios que possam cobri-lo.*

**Comportamento:** dica exibida após a tentativa.

**Tentar novamente:** sim. Permita que o usuário tente novamente.

### Mais de um rosto

`MULTIPLE_FACES`

**O que significa:** mais de um rosto foi encontrado na imagem, e a análise não conseguiu determinar com certeza qual deles pertence ao titular da conta.

**Causas comuns:**

* Outra pessoa atrás ou ao lado do usuário.
* Uma criança no colo do usuário.
* Uma foto, um pôster ou uma TV com rostos ao fundo.
* O reflexo do próprio usuário em um espelho.

**Mensagem recomendada:** *Certifique-se de que só seu rosto apareça na tela.*

**Comportamento:** dica exibida após a tentativa.

**Tentar novamente:** sim. Permita que o usuário tente novamente.

{% hint style="warning" %}
A mensagem deve pedir que somente o titular da conta apareça. Evite textos que incentivem a ajuda de outra pessoa durante a captura.
{% endhint %}

### Imagem desfocada

`FRAMES_BLURRY`

**O que significa:** as imagens capturadas não estavam nítidas o suficiente para a análise. Esse tipo também abrange movimento excessivo do rosto ou do dispositivo durante a captura.

**Causas comuns:**

* Um ambiente escuro combinado com um dispositivo tremendo, em que a câmera não consegue capturar imagens nítidas. Esse é o caso mais comum.
* O usuário caminhando ou dentro de um veículo em movimento.
* Ajustar a posição do celular no meio da captura.
* Uma lente da câmera frontal suja ou engordurada.
* Uma película ou capinha cobrindo a lente.
* O foco automático não se ajustou porque o rosto estava muito perto.
* Acessórios que cobrem parte do rosto, como um headset.

**Mensagem recomendada:** *Vá para um local bem iluminado, limpe a câmera frontal e mantenha o celular firme.*

**Comportamento:** dica exibida após a tentativa.

**Tentar novamente:** sim. Permita que o usuário tente novamente.

### Inconsistência de movimento

`MOTION_ISSUE`

**O que significa:** os dados de movimento registrados durante a captura não puderam ser usados pela análise. Além das imagens, a análise usa os dados de movimento enviados pelo dispositivo. Na maioria dos casos, esse tipo significa que o dispositivo não enviou esses dados corretamente, por exemplo, porque o sensor de movimento está ausente, com defeito ou não pôde ser lido.

**Causas comuns:**

* O dispositivo não envia os dados de movimento corretamente.
* Ausência de um padrão claro, por exemplo, com uma TV ou monitor ao fundo, com um fundo liso ou com o rosto de perfil.

Mover ou sacudir o celular para encaixar o rosto no oval geralmente não causa esse tipo: ele tende a retornar `FRAMES_BLURRY` ou `FACE_NOT_FOUND` em vez disso. Como `MOTION_ISSUE` também pode ser uma orientação genérica, talvez não reflita a causa real. Consulte [Como interpretar o `type`](#how-to-read-the-type).

**Como orientar o usuário:** mantenha o celular parado na altura dos olhos e mova apenas a cabeça para encaixar o rosto na oval. Uma nova tentativa no mesmo dispositivo costuma funcionar. Só faz sentido sugerir outro dispositivo após várias falhas consecutivas.

**Mensagem recomendada:**

* Primeira falha: *Mantenha o celular parado na altura dos olhos e encaixe o rosto na oval.*
* Falhas repetidas: *Mantenha o celular parado na altura dos olhos e encaixe o rosto na oval. Se o problema persistir, reinicie o dispositivo ou tente usar outro.*

**Comportamento:** na primeira falha, faça uma nova tentativa. Em caso de falhas repetidas, sugira reiniciar ou trocar de dispositivo apenas como dica secundária.

**Nova tentativa:** sim. Uma nova tentativa no mesmo dispositivo costuma funcionar. Se continuar falhando, sugira reiniciar o dispositivo ou usar outro.

{% hint style="warning" %}
Na primeira falha desse tipo, peça apenas uma nova captura com o celular parado. Não sugira trocar ou reiniciar o dispositivo logo de início: uma nova tentativa no mesmo dispositivo costuma funcionar. Se esse tipo de falha se repetir no mesmo dispositivo, o próximo passo é reiniciá-lo ou tentar usar outro dispositivo.
{% endhint %}

### Fundo ou contraste

`BACKGROUND_ISSUE`

**O que significa:** o fundo da imagem dificultou a separação do rosto em relação ao ambiente.

**Causas comuns:**

* Uma parede de cor semelhante ao tom da pele.
* Um fundo muito claro, com uma luz forte atrás do usuário.
* Um fundo com muitos elementos, padrões ou movimento.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** uma nova tentativa.

**Tentar novamente:** sim. Permita que o usuário tente novamente.

### Dispositivo ou ambiente

`DEVICE_ISSUE`

**O que significa:** esse tipo reúne falhas de diferentes naturezas, relacionadas ao comportamento do usuário, ao ambiente ou ao próprio dispositivo. A avaliação considera a qualidade da captura, as condições de iluminação, o contexto do dispositivo e o funcionamento da câmera.

**Causas comuns:**

* Baixa qualidade da captura.
* Iluminação desfavorável.
* Um problema na câmera, como quando ela está sendo usada por outro aplicativo ou ocorre uma falha momentânea.
* Configurações do dispositivo fora do padrão, como emulador, depuração ativada, jailbreak ou root.

Também é retornado quando a análise não identifica uma pessoa real diante da câmera, como orientação genérica. Consulte [Como interpretar o `type`](#how-to-read-the-type).

**Mensagem recomendada:**

* Primeira falha: *Não foi possível concluir a verificação. Tente novamente.*
* Falhas repetidas: *Não foi possível concluir a verificação. Tente novamente. Se o problema persistir, reinicie o dispositivo ou tente usar outro.*

**Comportamento:** na primeira falha, faça uma nova tentativa. Em caso de falhas repetidas, sugira reiniciar ou trocar de dispositivo apenas como dica secundária.

**Nova tentativa:** sim. Uma nova tentativa no mesmo dispositivo pode funcionar. Se continuar falhando, sugira reiniciar o dispositivo ou usar outro.

{% hint style="warning" %}
Na primeira falha desse tipo, peça apenas uma nova captura. Não sugira trocar ou reiniciar o dispositivo logo de início. Como esse tipo reúne causas de diferentes naturezas, a mensagem deve permanecer genérica e não deve sugerir um motivo específico.
{% endhint %}

{% hint style="info" %}
**Android:** versões de depuração e aplicativos instalados pelo ADB não passam pelas verificações de vivacidade nos ambientes de produção e teste. Com `enableSecurity = true` (o padrão), um aplicativo com depuração ativada é bloqueado antes pelas verificações do dispositivo da Certta, e o SDK retorna um erro `SECURITY_EXCEPTION` em vez de uma falha. Com `enableSecurity = false`, a captura é executada e retorna `DEVICE_ISSUE`. Consulte [Verificações de segurança](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/android/security-checks.md) antes de testar.
{% endhint %}

### Reinicialização do dispositivo

`DEVICE_RESTART`

**O que significa:** o dispositivo está em um estado que costuma ser resolvido com uma reinicialização.

**Causas comuns:**

* A câmera ou outros recursos do dispositivo ficaram travados após muito tempo sem reinicialização.
* Superaquecimento.
* Pouca memória disponível.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** uma nova tentativa.

**Nova tentativa:** sim. Uma nova tentativa no mesmo dispositivo pode funcionar. Se continuar falhando, sugira reiniciar o dispositivo ou usar outro.

{% hint style="info" %}
Não se espera que o modelo atual de análise de vivacidade retorne esse tipo. Continue tratando esse caso no seu aplicativo, caso ele seja retornado.
{% endhint %}

{% hint style="info" %}
Para sua equipe de suporte: quando um usuário entrar em contato após falhas repetidas desse tipo, geralmente pedir que reinicie o dispositivo resolve o problema.
{% endhint %}

### Erro do sistema

`SYSTEM_ERROR`

**O que significa:** a análise de vivacidade é feita por um modelo de IA que trabalha com níveis de confiança. Por isso, algumas capturas não atingem o nível de confiança necessário para serem aprovadas ou se encaixarem em uma falha mais específica. Quando isso acontece, ou quando ocorre uma falha interna durante o processamento, a análise retorna `SYSTEM_ERROR`. Isso não significa que o usuário fez algo errado e, na maioria dos casos, basta tentar novamente para concluir a verificação.

**Causas comuns:**

* O modelo de IA não conseguiu classificar a captura com confiança suficiente, e a situação não se encaixa em nenhuma das falhas mais específicas.
* Uma mudança repentina na iluminação durante a captura, como uma luz ser acesa ou apagada.
* Instabilidade momentânea no ambiente de processamento.
* Uma falha pontual de comunicação entre os componentes que processam a análise.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** uma nova tentativa.

**Tentar novamente:** sim. Se o problema continuar acontecendo, entre em contato com o suporte da Certta.

### Usuário não cadastrado

`USER_NOT_FOUND`

**O que significa:** não há um registro biométrico do usuário para comparar com a captura.

**Quando acontece:** somente em fluxos que comparam o rosto com um rosto cadastrado anteriormente, como na autenticação facial. Nunca acontece em fluxos apenas de prova de vivacidade ou de cadastro.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** encaminhe o usuário para o cadastro ou para outro canal.

**Nova tentativa:** não. Tentar novamente não resolve o problema.

{% hint style="warning" %}
Nunca informe ao usuário que ele não está cadastrado. Mantenha a mesma mensagem usada para as outras falhas e encaminhe o usuário para o cadastro ou outro canal do seu lado.
{% endhint %}

{% hint style="info" %}
Não se espera que o modelo atual de análise de vivacidade retorne esse tipo. Continue tratando esse caso no seu aplicativo, caso ele seja retornado.
{% endhint %}

### Transação rejeitada

`REJECTED`

**O que significa:** a captura foi realizada, mas a transação foi recusada porque o usuário está em uma lista de bloqueio. Essa lista pode ser mantida pelo serviço de prova de vivacidade, com base em ataques já identificados, ou fornecida pelo cliente para usuários que não devem ser aprovados. A recusa não está relacionada à qualidade da captura nem ao ambiente.

**Causas comuns:**

* Um usuário associado a tentativas de fraude identificadas anteriormente pelo serviço de prova de vivacidade.
* Um usuário incluído pelo cliente na própria lista de bloqueio.

Essa situação é rara.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** nova tentativa, com o mesmo comportamento visível das outras falhas.

**Nova tentativa:** sim, com um limite de tentativas definido por você. Tentar novamente não altera o resultado. Consulte o aviso abaixo.

{% hint style="warning" %}
Nunca informe ao usuário que ele está bloqueado ou que existe uma lista de bloqueio. A mensagem e o comportamento da tela devem ser iguais aos das outras falhas, para que alguém tentando burlar o fluxo não consiga identificar o motivo da recusa. Tentar novamente não altera o resultado; portanto, aplique um limite de tentativas do seu lado e encaminhe o usuário para um canal alternativo ou para uma análise manual.
{% endhint %}

{% hint style="info" %}
Para sua equipe de suporte: quando um usuário entrar em contato após falhas repetidas desse tipo, primeiro verifique se ele está na sua própria lista de bloqueio. Se não estiver, analise o caso com a Certta.
{% endhint %}

### Tempo limite atingido

`TIMEOUT`

**O que significa:** a sessão ultrapassou o limite de tempo do sistema antes de ser concluída.

**Causas comuns:**

* Uma conexão lenta ou instável durante o envio da captura.
* Um atraso no processamento da análise.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** uma nova tentativa.

**Tentar novamente:** sim. Se o problema continuar acontecendo, entre em contato com o suporte da Certta.

{% hint style="info" %}
Quando o usuário abre a captura e não posiciona o rosto antes de o tempo de captura terminar, o SDK não retorna esse tipo. A execução termina com um `PROCESSING_FAULT` falha. Consulte [Falha no processamento](#processing-failure).
{% endhint %}

### Falha no processamento

`PROCESSING_FAULT`

**O que significa:** a captura foi concluída, mas não pôde ser processada.

**Causas comuns:**

* O tempo de captura terminou antes que o usuário posicionasse o rosto dentro da oval.
* Um ambiente escuro combinado com um dispositivo tremendo.
* Um upload interrompido ou incompleto porque a conexão caiu.
* Uma falha momentânea no serviço de análise.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Comportamento:** uma nova tentativa.

**Tentar novamente:** sim. Se o problema continuar acontecendo, entre em contato com o suporte da Certta.

{% hint style="warning" %}
Um `PROCESSING_FAULT` não retorna uma imagem do resultado. Quando seu back-end recupera o resultado dessa tentativa, não há imagem disponível; portanto, qualquer etapa que dependa dela, como a correspondência facial ou o salvamento de uma foto de referência, não pode ser executada. Considere essa tentativa como uma tentativa sem imagem e peça ao usuário que faça uma nova captura.
{% endhint %}

## Tipos legados

Os tipos abaixo ainda são declarados em `CafFailureType` para que as integrações existentes continuem compilando, mas as versões atuais não os retornam mais. Agora, o serviço de prova de vida retorna o tipo na **Retornado agora como** coluna para as mesmas situações.

Se seu aplicativo já trata esses tipos, mantenha o código e mapeie cada um para a mesma mensagem do equivalente atual.

| Android                          | iOS                          | Retornado agora como                                                                                                                          | Mensagem recomendada                                                               |
| -------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `TOO_BRIGHT`, `TOO_DARK`         | `tooBright`, `tooDark`       | [`LIGHTING_ISSUES`](#unsuitable-lighting)                                                                                                     | Verifique se seu rosto está bem iluminado e sem reflexos.                          |
| `SUNGLASSES`                     | `sunglasses`                 | [`EYEWEAR`](#eye-area-not-confirmed)                                                                                                          | Verifique se seus olhos estão visíveis.                                            |
| `MISALIGNED_FACE`                | `misalignedFace`             | [`FACE_NOT_FOUND`](#face-position-in-the-guide)                                                                                               | Mantenha a câmera frontal na altura dos olhos.                                     |
| `TOO_MUCH_MOVEMENT`              | `tooMuchMovement`            | [`FRAMES_BLURRY`](#blurry-image)                                                                                                              | Procure um local bem iluminado, limpe a câmera frontal e mantenha o celular firme. |
| `FACE_TOO_FAR`, `FACE_TOO_CLOSE` | `faceTooFar`, `faceTooClose` | Nenhuma falha. A captura não começa enquanto o rosto estiver muito longe ou muito perto, e a tela de captura orienta o usuário em tempo real. | Mantenha a câmera frontal na altura dos olhos.                                     |

## Novas tentativas e investigação

### Permitir novas tentativas

* Permita pelo menos **duas** tentativas. A prática recomendada é permitir três.
* Acompanhe a **conclusão em até três tentativas por usuário** junto com a taxa de aprovação na primeira tentativa. À medida que sua base de usuários cresce, espere que alguns usuários legítimos precisem de mais de uma tentativa.
* Cada tentativa é avaliada individualmente. Um usuário legítimo pode falhar em uma tentativa e ser aprovado na seguinte, aparentemente nas mesmas condições. Esse é o sistema funcionando conforme projetado.

### Ajudar os usuários a passar na primeira tentativa

Mostre orientações visuais e breves antes da captura. Estas dicas abrangem a maioria das falhas:

* Segure o telefone na altura dos olhos e alinhe o rosto dentro da oval.
* Mova a cabeça, não o telefone, para alinhar o rosto à oval.
* Assim que o rosto estiver dentro da oval, fique imóvel até o fim da captura.
* Certifique-se de que o rosto esteja bem iluminado, sem uma luz forte atrás do usuário.
* Mantenha o rosto inteiro visível, com os olhos abertos.
* Evite capturar imagens dentro de um veículo em movimento.

### Investigação de casos

* Analise a conclusão por usuário, não tentativas isoladas.
* Procure padrões por modelo do dispositivo, versão do sistema operacional e versão do SDK.
* Confira os tipos de falha retornados em cada tentativa.
* Compare cada caso com as orientações desta página antes de encaminhá-lo.

Ao encaminhar um caso ao suporte da Certta, envie a data e a hora, o tipo de falha `type` e o `signedResponse` de **todas as tentativas** do usuário.


---

# 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-falhas/mobile/failure-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.
