> 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/getting-started-with-the-sdk/handling-failures.md). # Tratando falhas {% hint style="warning" %} Este guia abrange a versão 7.14.0 e superior. Para versões anteriores à 7.14.0, consulte a [documentação legada](https://docs.caf.io/caf-sdk/android/getting-started-with-the-sdk-1). {% endhint %} Quando uma verificação de vivacidade falha, o SDK retorna um `LivenessFailure` objeto. Este objeto contém um `causa` parâmetro, que é um identificador de string que informa exatamente por que o processo não teve sucesso. Compreender e tratar o `causa` 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. ### Os Modelos de Falha O SDK usa uma hierarquia de classes seladas para categorizar falhas. Tanto as falhas no nível de captura quanto as falhas no nível de reconhecimento herdam da classe base `LivenessFailure` para que você possa sempre acessar a `causa` string. {% code title="LivenessFailure.kt" %} ```kotlin public sealed class LivenessFailure(public open val cause: String) { // Disparado quando o processo de captura de imagem falha. Nenhuma imagem (resposta) disponível public data class ImageCaptureFailure(override val cause: String) : LivenessFailure(cause) // Disparado quando falha ao reconhecer ou autenticar o rosto. public data class FaceRecognitionFailure( public val response: String, override val cause: String ) : LivenessFailure(cause) } ``` {% endcode %} {% hint style="warning" %} Garanta que a resposta JWT seja avaliada no backend. Esse processo deve incluir a validação da assinatura do token e a verificação dos `estáVivo` e `éCorrespondente` campos. Não realize essas validações no lado do cliente. {% endhint %} ### Usando o `causa` Parâmetro O `causa` parâmetro retorna uma string de constante bruta (por exemplo, `"TOO_DARK"` ou `"FACE_TOO_FAR"`). Prática recomendada: não exiba essas strings brutas diretamente aos seus usuários finais. Em vez disso, interceptar a `causa` string e mapeá-la para uma mensagem amigável e localizada na interface do seu app, orientando-os sobre como corrigir o problema. #### Causas de Falha Disponíveis Ao usar o [Iproov](https://github.com/iProov/android) provedor, se a captura de imagem for bem-sucedida, mas o mecanismo falhar ao autenticar ou processar o rosto, o SDK retorna uma `FaceRecognitionFailure`. Abaixo está a lista dos possíveis `causa` valores retornados especificamente durante esta fase: | Causa | Descrição | | :-----------------: | -------------------------------- | | `UNKNOWN` | Falha genérica | | `TOO_MUCH_MOVEMENT` | Movimento excessivo da cabeça | | `TOO_BRIGHT` | Iluminação excessiva | | `TOO_DARK` | Condições de pouca luz | | `MISALIGNED_FACE` | Falha no alinhamento do rosto | | `FACE_TOO_FAR` | Rosto muito distante | | `FACE_TOO_CLOSE` | Rosto muito próximo | | `SUNGLASSES` | Óculos que obstruem os olhos | | `OBSCURED_FACE` | Obstrução parcial do rosto | | `EYES_CLOSED` | Olhos fechados durante a captura | | `MULTIPLE_FACES` | Vários rostos detectados | | `BACKGROUND_ISSUE` | Plano de fundo inadequado | | `DEVICE_ISSUE` | Dispositivo incompatível | | `EYEWEAR` | Óculos detectados | | `FACE_NOT_FOUND` | Falha na detecção do rosto | | `FRAMES_BLURRY` | Quadros borrados detectados | | `MOTION_ISSUE` | Erro de movimento do dispositivo | | `LIGHTING_ISSUES` | Condições de iluminação ruins | | `REJECTED` | Transação rejeitada | | `SYSTEM_ERROR` | Erro interno do sistema | | `TIMEOUT` | Tempo limite da sessão | | `USER_NOT_FOUND` | Falha na busca do usuário | | `DEVICE_RESTART` | Erro de estado do dispositivo | | `PROCESSING_FAULT` | Erro de processamento | ### Exemplo de implementação Aqui está um exemplo de como você pode lidar com um `LivenessFailure` e mapear o `causa` parâmetro para uma orientação útil ao usuário: {% tabs %} {% tab title="Kotlin" %} ```kotlin fun handleLivenessError(failure: LivenessFailure) { // 1. Você pode verificar o tipo específico da falha, se necessário when (failure) { is LivenessFailure.ImageCaptureFailure -> { println("A captura falhou antes de chegar ao servidor.") } is LivenessFailure.FaceRecognitionFailure -> { println("O servidor rejeitou a captura. Resposta: ${failure.response}") } } // 2. Mapear o 'cause' para uma mensagem amigável ao usuário val userMessage = when (failure.cause) { "TOO_DARK" -> "Está um pouco escuro demais. Por favor, vá para um local mais claro." "FACE_TOO_FAR" -> "Por favor, aproxime o celular do seu rosto." "EYES_CLOSED" -> "Por favor, mantenha os olhos abertos e olhe diretamente para a câmera." "MULTIPLE_FACES" -> "Certifique-se de que você seja a única pessoa no enquadramento." "TIMEOUT" -> "O tempo acabou. Tente novamente quando estiver pronto." "REJECTED", "FACE_AUTHENTICATION" -> "Não foi possível verificar seu rosto. Tente novamente." //... else -> "Ocorreu um erro inesperado (${failure.cause}). Tente novamente." } // 3. Exiba a mensagem na sua interface showErrorDialog(userMessage) } ``` {% endtab %} {% tab title="Java" %} {% code title="" %} ```java public void handleLivenessError(LivenessFailure failure) { // 1. Você pode verificar o tipo específico da falha, se necessário if (failure instanceof LivenessFailure.ImageCaptureFailure) { System.out.println("A captura falhou antes de chegar ao servidor."); } else if (failure instanceof LivenessFailure.FaceRecognitionFailure) { // Faça o cast para acessar propriedades específicas, como response LivenessFailure.FaceRecognitionFailure recognitionFailure = (LivenessFailure.FaceRecognitionFailure) failure; System.out.println("O servidor rejeitou a captura. Resposta: " + recognitionFailure.getResponse()); } // 2. Mapear o 'cause' para uma mensagem amigável ao usuário String userMessage; String cause = failure.getCause(); switch (cause) { case "TOO_DARK": userMessage = "Está um pouco escuro demais. Por favor, vá para um local mais claro."; break; case "FACE_TOO_FAR": userMessage = "Por favor, aproxime o celular do seu rosto."; break; case "EYES_CLOSED": userMessage = "Por favor, 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 foi possível verificar seu rosto. Tente novamente."; break; //... default: userMessage = "Ocorreu um erro inesperado (" + cause + "). Tente novamente."; break; } // 3. Exiba a mensagem na sua interface showErrorDialog(userMessage); } ``` {% endcode %} {% endtab %} {% endtabs %} --- # 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/getting-started-with-the-sdk/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.