> 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.md).

# Móvel

Uma falha significa que a captura foi executada e avaliada, mas o usuário não foi aprovado. O SDK Android a entrega como um `LivenessLiteEvent.Failure` para o `FaceLivenessLiteListener` que você passou para `startLiveness()`. O SDK do iOS chama `didFinishWithFailure(type:description:signedResponse:)` no seu `CafFaceLivenessLiteDelegate`.

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

```kotlin
CafFaceLivenessLite.instance.startLiveness { event ->
    if (event is LivenessLiteEvent.Failure) {
        handleFailure(event)
    }
}
```

{% endtab %}

{% tab title="iOS" %}

```swift
extension YourViewController: CafFaceLivenessLiteDelegate {
    func didFinishWithFailure(type: CafFailureType, description: String?, signedResponse: String?) {
        handleFailure(type, signedResponse)
    }
}
```

{% endtab %}
{% endtabs %}

Uma falha é sempre o último resultado de uma execução: depois dela, nenhum outro resultado é enviado para essa execução. No Android, os eventos chegam na thread principal, então você pode atualizar a interface diretamente a partir do listener.

## De Onde Vêm as Falhas

As falhas são decididas pelo mecanismo de liveness após a captura, não pelo dispositivo. O SDK passa o motivo do mecanismo para seu app como um `CafFailureType`. Quando o mecanismo retorna um motivo que o SDK não conhece, o tipo é `UNKNOWN` (`unknown` no iOS).

Os tipos de falha são os mesmos nas duas plataformas, com grafias diferentes: o Android usa `UPPER_SNAKE_CASE` (`TOO_MUCH_MOVEMENT`) e o iOS usa `lowerCamelCase` (`tooMuchMovement`). Esta página usa os nomes do Android; 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#quick-reference) para ambos.

| Grupo                | O que significa                                                                | Tipos                                                                                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Condições de captura | A luz, a posição do rosto ou o movimento do usuário impediram uma boa captura. | `TOO_MUCH_MOVEMENT`, `TOO_BRIGHT`, `TOO_DARK`, `LIGHTING_ISSUES`, `MISALIGNED_FACE`, `FACE_TOO_FAR`, `FACE_TOO_CLOSE`, `FACE_NOT_FOUND`, `FRAMES_BLURRY`, `BACKGROUND_ISSUE` |
| Rosto                | Algo no rosto ou ao redor dele bloqueou a verificação.                         | `SUNGLASSES`, `EYEWEAR`, `OBSCURED_FACE`, `EYES_CLOSED`, `MULTIPLE_FACES`                                                                                                    |
| Dispositivo          | O dispositivo, ou a forma como o app foi construído ou instalado, não passou.  | `DEVICE_ISSUE`, `MOTION_ISSUE`, `DEVICE_RESTART`                                                                                                                             |
| Processamento        | O mecanismo não conseguiu concluir a avaliação.                                | `SYSTEM_ERROR`, `TIMEOUT`, `PROCESSING_FAULT`, `UNKNOWN`                                                                                                                     |
| Decisão              | A avaliação foi concluída e a tentativa não foi aceita.                        | `REJECTED`, `USER_NOT_FOUND`                                                                                                                                                 |

{% hint style="info" %}
Quando a execução não pode começar ou não pode terminar, o SDK retorna um erro em vez disso, sem nenhuma captura avaliada. Veja [Erros do Android](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/android.md) e [Erros do iOS](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios.md).
{% endhint %}

## O que o SDK faz quando ocorre uma falha

* Entrega a falha com uma **resposta assinada** do servidor, assim como em um sucesso.
* Registra a tentativa no backend da Certta em segundo plano, para que ela possa ser processada e consultada depois.
* Fecha a tela de captura e a tela de carregamento, e interrompe o monitoramento de segurança.
* Encerra a execução, para que uma nova captura possa ser iniciada imediatamente.

A configuração é mantida. Para permitir que o usuário tente novamente, chame `startLiveness()` (Android) ou `startSDK(viewController:)` (iOS) novamente.

## O que seu app deve fazer

1. **Envie a resposta assinada para o seu backend.** A falha carrega uma resposta assinada, assim como um sucesso. Valide-a no seu backend e use-a como fonte de verdade. Nunca decida o resultado no dispositivo.
2. **Oriente o usuário.** Mapeie o `parâmetro` para uma mensagem localizada que diga ao usuário o que mudar, como "Mude para um local mais iluminado". Não exiba o `description` ou nomes de enumeração aos seus usuários.
3. **Tente novamente apenas quando isso puder ajudar.**

| Grupo                | Tentar novamente?                                                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Condições de captura | Sim. Diga ao usuário o que mudar e depois permita que ele tente novamente.                                                                     |
| Rosto                | Sim. Peça ao usuário que remova o que está bloqueando o rosto ou que fique sozinho no enquadramento.                                           |
| Dispositivo          | Sim. Uma nova tentativa no mesmo dispositivo pode funcionar. Se continuar falhando, ofereça outro dispositivo ou outro caminho de verificação. |
| Processamento        | Sim, por um número limitado de vezes. Se continuar acontecendo, entre em contato com o suporte da CAF.                                         |
| Decisão              | Siga as regras do seu negócio. Tentar novamente com o mesmo usuário geralmente retorna a mesma decisão.                                        |

{% hint style="info" %}
**Android:** `DEVICE_ISSUE` também é retornado quando o app não passa nas verificações de injeção do mecanismo de liveness, por exemplo, uma build de debug ou um app instalado via ADB. Veja [Verificações de segurança](/sdk-lite/sdk-lite-english-pt-br/configuracao/android/security-checks.md) antes de testar.
{% endhint %}

## Cancelado Não é uma Falha

Quando o usuário fecha ou sai da tela de captura, o SDK entrega `LivenessLiteEvent.Cancelled` (Android) ou chama `cancelled()` (iOS). Não é nem um erro nem uma falha: volte para a tela anterior sem exibir uma mensagem de erro.

## Depuração no Android

Para ver os logs do SDK no Logcat enquanto você investiga uma falha, habilite o logging:

```kotlin
CafFaceLivenessLite.isLogEnabled = true
```

Os logs só aparecem quando seu app é debuggable. Em builds de release, essa flag é ignorada, então o SDK nunca registra dados sensíveis como o token ou a resposta assinada em produção.

## Próximos passos

Para o modelo de falhas e cada tipo de falha em detalhes: [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)

Para como o seu backend lida com a `signedResponse` que vem com uma falha: [Falhas do Backend](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/backend.md)


---

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