> 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 a entrega ao seu app como um resultado de falha com três valores: o tipo de falha, uma descrição técnica e a resposta assinada do servidor.

Uma falha é sempre o último resultado de uma execução. Depois dela, nenhum outro resultado é enviado para essa execução.

## Tipos de falha

As falhas são decididas pelo mecanismo de liveness após a captura, e não pelo dispositivo. O tipo de falha é o motivo mais provável do mecanismo.

Os tipos são os mesmos em ambas as plataformas, escritos no estilo de nomenclatura de cada plataforma. Veja [Motivos da falha e orientação ao usuário](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/failure-handling.md#quick-reference) cada tipo em detalhes.

<table><thead><tr><th width="102.79296875">Grupo</th><th>O que significa</th><th>Android</th><th>iOS</th></tr></thead><tbody><tr><td>Condições de captura</td><td>A luz, a posição do rosto ou o movimento do usuário impediram uma boa captura.</td><td><code>MOTION_ISSUE</code>, <code>LIGHTING_ISSUES</code>, <code>FACE_NOT_FOUND</code>, <code>FRAMES_BLURRY</code>, <code>BACKGROUND_ISSUE</code></td><td><code>motionIssue</code>, <code>lightingIssues</code>, <code>faceNotFound</code>, <code>framesBlurry</code>, <code>backgroundIssue</code></td></tr><tr><td>Rosto</td><td>Algo no rosto ou ao redor dele bloqueou a verificação.</td><td><code>EYES_CLOSED</code>, <code>EYEWEAR</code>, <code>OBSCURED_FACE</code>, <code>MULTIPLE_FACES</code></td><td><code>eyesClosed</code>, <code>eyewear</code>, <code>obscuredFace</code>, <code>multipleFaces</code></td></tr><tr><td>Dispositivo</td><td>O dispositivo, ou a forma como o app foi construído ou instalado, não passou.</td><td><code>DEVICE_ISSUE</code>, <code>DEVICE_RESTART</code></td><td><code>deviceIssue</code>, <code>deviceRestart</code></td></tr><tr><td>Processamento</td><td>O mecanismo não conseguiu concluir a avaliação. A causa não é o usuário.</td><td><code>UNKNOWN</code>, <code>SYSTEM_ERROR</code>, <code>REJECTED</code>, <code>TIMEOUT</code>, <code>PROCESSING_FAULT</code></td><td><code>desconhecido</code>, <code>systemError</code>, <code>rejected</code>, <code>timeout</code>, <code>processingFault</code></td></tr><tr><td>Registro</td><td>Não há um registro biométrico do usuário para comparação. Apenas em fluxos que comparam o rosto com um registrado.</td><td><code>USER_NOT_FOUND</code></td><td><code>userNotFound</code></td></tr></tbody></table>

A enumeração também declara tipos legados que as versões atuais não retornam mais, como `TOO_DARK` e `FACE_TOO_FAR`. Veja [Tipos Legados](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/failure-handling.md#legacy-types) para o equivalente atual de cada um.

{% 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](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/android.md) e [Erros do iOS](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios.md).
{% endhint %}

## O que o SDK faz quando acontece 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, então você pode iniciar o SDK novamente sem configurá-lo outra vez.

## O que seu app deve fazer

1. **Envie a resposta assinada para o seu backend.** Valide-a no seu backend e use-a como fonte da verdade. Nunca decida o resultado no dispositivo.
2. **Oriente o usuário.** Associe o tipo de falha a uma mensagem localizada que diga ao usuário o que fazer na próxima tentativa. Não mostre a descrição nem os nomes dos tipos aos seus usuários.
3. **Permita que o usuário tente novamente quando isso puder ajudar.** Cada tipo de falha em [Motivos da falha e orientação ao usuário](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/failure-handling.md) indica se uma nova tentativa ajuda.

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

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

        val message = when (event.type) {
            CafFailureType.LIGHTING_ISSUES -> getString(R.string.liveness_lighting)
            CafFailureType.FACE_NOT_FOUND -> getString(R.string.liveness_face_position)
            // ...
            else -> getString(R.string.liveness_try_again)
        }

        showRetryDialog(message)
    }
}
```

{% endtab %}

{% tab title="iOS" %}

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

        let message: String
        switch type {
        case .lightingIssues:
            message = NSLocalizedString("liveness_lighting", comment: "")
        case .faceNotFound:
            message = NSLocalizedString("liveness_face_position", comment: "")
        // ...
        default:
            message = NSLocalizedString("liveness_try_again", comment: "")
        }

        showRetryDialog(message)
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
`DEVICE_ISSUE` (`deviceIssue` no iOS) 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. No Android, com `enableSecurity = true` (o padrão), uma build de debug é bloqueada antes pelas verificações de dispositivo da Certta e retorna um `SECURITY_EXCEPTION` erro em vez disso. Antes de testar, veja a página de verificações de segurança para [Android](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/android/security-checks.md) e [iOS](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/security-checks.md).
{% endhint %}

## Cancelado Não é uma Falha

Quando o usuário fecha a tela de captura ou envia o app para o segundo plano durante a captura, o SDK entrega um resultado cancelado. Não é nem um erro nem uma falha: volte para a tela anterior sem mostrar uma mensagem de erro.

## Depuração

Para investigar uma falha, ative os logs do SDK. Os logs só aparecem quando seu app é depurável, então o SDK nunca registra dados sensíveis, como o token ou a resposta assinada, em produção.

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

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

{% endtab %}
{% endtabs %}

## Próximas etapas

Para cada tipo de falha em detalhes: [Motivos da falha e orientação ao usuário](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/failure-handling.md)

Sobre como o seu backend lida com a resposta assinada que vem com uma falha: [Falhas de backend](https://docs.caf.io/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.
