> 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/caf-sdk/caf-sdk-pt-br/android/standalone-modules/caffacelivenesslite/handling-failures.md). # Tratando falhas links: [Face Liveness Lite](https://app.gitbook.com/o/WK99k3S40M3U65yN1uet/s/vnCLbngSdfkIVoF3ziNX/~/edit/~/changes/96/android/standalone-modules/caffacelivenesslite) Quando uma verificação de liveness falha, o SDK retorna um `evento LivenessLiteEvent.Failure` evento. Esse evento contém um `tipo` parâmetro, `CafFailureType` enumeração que informa exatamente por que o processo não foi bem-sucedido. Entender e lidar com o `tipo` parâmetro é fundamental para fornecer um feedback claro e acionável aos seus usuários, para que eles possam corrigir o problema e tentar novamente. #### O Modelo de Falha O SDK entrega falhas por meio da `LivenessLiteEvent` interface selada. Tanto falhas no nível de captura quanto no nível de reconhecimento são relatadas como `evento LivenessLiteEvent.Failure`, garantindo que você sempre possa acessar a `tipo` e `descrição`. {% code title="LivenessLiteEvent.kt" %} ```kotlin public sealed interface LivenessLiteEvent { /** * Evento de falha de liveness com tipo de falha específico. * * @param response A resposta assinada do servidor * @param type O tipo específico de falha que ocorreu * @param description Descrição amigável da falha */ public data class Failure( val response: String, val type: CafFailureType, val description: String ) : LivenessLiteEvent } ``` {% endcode %} {% hint style="warning" %} Certifique-se de que a resposta JWT seja avaliada no backend. Esse processo deve incluir a validação da assinatura do token e a verificação dos `isAlive` e `isMatch` campos. Não realize essas validações no lado do cliente. {% endhint %} #### Usando o `tipo` Parâmetro O `tipo` parâmetro retorna uma `CafFailureType` constante de enumeração (por exemplo, `TOO_DARK` ou `FACE_TOO_FAR`). Prática recomendada: não exiba o nome bruto do enum ou o `descrição` diretamente para seus usuários finais. Em vez disso, intercepte o `tipo` e mapeie-o para uma mensagem localizada e amigável ao usuário na UI do seu app para orientá-los sobre como corrigir o problema. **Tipos de falha disponíveis** Se a captura da imagem for bem-sucedida, mas o mecanismo falhar ao autenticar ou processar o rosto, o SDK retorna um `evento LivenessLiteEvent.Failure`. Abaixo está a lista dos possíveis `CafFailureType` valores retornados durante esta fase: | Tipo | Descrição | | :------------------------------: | -------------------------------- | | `DESCONHECIDO` | Falha genérica | | `MOVIMENTO_DEMAIS` | Movimento excessivo da cabeça | | `MUITO_CLARO` | Excesso de iluminação | | `TOO_DARK` | Condições de pouca luz | | `ROSTO_DESALINHADO` | Falha no alinhamento facial | | `FACE_TOO_FAR` | Rosto muito distante | | `ROSTO_MUITO_PERTO` | Rosto muito perto | | `ÓCULOS_ESCUROS` | Óculos que ocultam os olhos | | `ROSTO_OBSCURECIDO` | Obstrução parcial do rosto | | `OLHOS_FECHADOS` | Olhos fechados durante a captura | | `VÁRIOS_ROSTOS` | Vários rostos detectados | | `PROBLEMA_DE_FUNDO` | Fundo inadequado | | `PROBLEMA_NO_DISPOSITIVO` | Dispositivo incompatível | | `ÓCULOS` | Óculos detectados | | `ROSTO_NÃO_ENCONTRADO` | Falha na detecção do rosto | | `QUADROS_BORRADOS` | Quadros borrados detectados | | `PROBLEMA_DE_MOVIMENTO` | Erro de movimento do dispositivo | | `PROBLEMAS_DE_ILUMINAÇÃO` | Condições de iluminação ruins | | `RECUSADO` | Transação recusada | | `ERRO_DE_SISTEMA` | Erro interno do sistema | | `TEMPO_ESGOTADO` | Tempo limite da sessão | | `USUÁRIO_NÃO_ENCONTRADO` | Falha na busca do usuário | | `REINICIALIZAÇÃO_DO_DISPOSITIVO` | Erro de estado do dispositivo | | `FALHA_DE_PROCESSAMENTO` | Erro de processamento | | `AUTENTICAÇÃO_FACIAL` | Falha na autenticação facial | #### Exemplo de Implementação Aqui está um exemplo de como você pode lidar com um `evento LivenessLiteEvent.Failure` e mapear o `tipo` parâmetro para orientações úteis ao usuário: {% tabs %} {% tab title="Kotlin" %} ```kotlin fun handleLivenessFailure(failure: LivenessLiteEvent.Failure) { // 1. A carga útil assinada do servidor está disponível, se necessário println("Resposta do servidor: ${failure.response}") // 2. Mapeie o 'type' para uma mensagem amigável ao usuário val userMessage = when (failure.type) { CafFailureType.TOO_DARK -> "Está um pouco escuro demais. Por favor, vá para um ambiente mais claro." CafFailureType.FACE_TOO_FAR -> "Aproxime o telefone do seu rosto." CafFailureType.EYES_CLOSED -> "Mantenha os olhos abertos e olhe diretamente para a câmera." CafFailureType.MULTIPLE_FACES -> "Certifique-se de que você seja a única pessoa no enquadramento." CafFailureType.TIMEOUT -> "O tempo acabou. Tente novamente quando estiver pronto." CafFailureType.REJECTED, CafFailureType.FACE_AUTHENTICATION -> "Não conseguimos verificar seu rosto. Tente novamente." //... else -> "Ocorreu um erro inesperado (${failure.type}). Tente novamente." } // 3. Exiba a mensagem na sua UI showErrorDialog(userMessage) } ``` {% endtab %} {% tab title="Java" %} {% code title="" %} ```java public void handleLivenessFailure(LivenessLiteEvent.Failure failure) { // 1. A carga útil assinada do servidor está disponível, se necessário System.out.println("Resposta do servidor: " + failure.getResponse()); // 2. Mapeie o 'type' para uma mensagem amigável ao usuário String userMessage; switch (failure.getType()) { case TOO_DARK: userMessage = "Está um pouco escuro demais. Por favor, vá para um ambiente mais claro."; break; case FACE_TOO_FAR: userMessage = "Aproxime o telefone do seu rosto."; break; case EYES_CLOSED: userMessage = "Mantenha os olhos abertos e olhe diretamente para a câmera."; break; case MULTIPLE_FACES: userMessage = "Certifique-se de que você seja a única pessoa no enquadramento."; break; case TIMEOUT: userMessage = "O tempo acabou. Tente novamente quando estiver pronto."; break; case REJECTED: case FACE_AUTHENTICATION: userMessage = "Não conseguimos verificar seu rosto. Tente novamente."; break; //... default: userMessage = "Ocorreu um erro inesperado (" + failure.getType() + "). Tente novamente."; break; } // 3. Exiba a mensagem na sua UI showErrorDialog(userMessage); } ``` {% endcode %} {% endtab %} {% endtabs %} Links: {% content-ref url="/pages/dc4cd36c7463361a88fcc7d56b9c2bd341ce5b6e" %} [Face Liveness Lite](/caf-sdk/caf-sdk-pt-br/android/standalone-modules/caffacelivenesslite.md) {% endcontent-ref %} {% content-ref url="/pages/81448022d7df70d98c5eb3cf72e49fe05e6df99b" %} [Tratando falhas](/caf-sdk/caf-sdk-pt-br/android/getting-started-with-the-sdk/handling-failures.md) {% endcontent-ref %} {% content-ref url="/pages/4f5e1dfedd1017d3b6433c571a904439a138bbf1" %} [Personalização da UI](/caf-sdk/caf-sdk-pt-br/android/standalone-modules/caffacelivenesslite/personalizacao-da-ui.md) {% endcontent-ref %} {% content-ref url="/pages/fe433841f24be5e1ede569091ecfd49f66b5007b" %} [Registro de alterações](/caf-sdk/caf-sdk-pt-br/android/standalone-modules/caffacelivenesslite/changelog.md) {% endcontent-ref %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/android/standalone-modules/caffacelivenesslite/handling-failures.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.