> 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/handling-failures.md). # Razões da falha e orientações para o usuário Quando a captura vai até o final, mas não é aprovada, o SDK retorna um `Falha` evento. Seu `tipo` parâmetro, um `CafFailureType` enum, fornece o motivo mais provável, para que você possa orientar o usuário a ser aprovado na próxima tentativa. A maioria das falhas pode ser resolvida pelo usuário com boas orientações sobre luz, distância, posição e estabilidade. ## A Estrutura da Falha {% 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 do servidor. Envie-o para o seu backend, assim como um sucesso. | | `tipo` | O motivo mais provável da falha. Use-o para escolher a mensagem ao usuário. | | `description` | Uma mensagem técnica em inglês. Use-a em logs, não para os usuários finais. | {% hint style="warning" %} Nunca decida o resultado no dispositivo. Seu backend valida a resposta assinada (assinatura e `tokenId`) e então recupera o resultado final, incluindo `isAlive`, com o `livenessAttemptId` que ela carrega. Veja [Configuração do Backend](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md). {% endhint %} ### Como Ler o `tipo` A análise de liveness é 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 parece corresponder ao que aconteceu. Por exemplo, ele pode indicar luz demais em um ambiente que parece normalmente iluminado, ou óculos em uma pessoa que não está usando óculos. Trate o `tipo` como uma indicação da causa mais provável, e 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, sem garantia de que sejam a causa real em uma sessão específica. ### Regras para Todas as Mensagens 1. **Oriente a próxima tentativa.** Durante a captura, a tela de captura já mostra instruções em tempo real, como "Aproxime-se" ou "Por favor, fique parado". As mensagens desta página são exibidas após uma tentativa malsucedida, então elas dizem o que fazer na próxima. 2. **Segurança acima da especificidade.** Nunca diga ao usuário que há suspeita de fraude, qual verificação de segurança falhou ou se um rosto está cadastrado para uma pessoa. Essas informações ajudam quem está tentando burlar a jornada. 3. **Tom neutro.** As mensagens descrevem o que fazer, sem dizer o que a pessoa fez de errado. A leitura do modelo pode estar errada, e uma mensagem acusatória piora a experiência para usuários legítimos. {% hint style="info" %} **Observação:** 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 a segurança da jornada. {% endhint %} ## Referência Rápida Os tipos de falha são os mesmos nas duas plataformas, com grafia diferente. A tabela mostra ambos. | Android | iOS | Motivo | Mensagem recomendada | | -------------------------------------------- | ----------------------------------------- | ----------------------------- | -------------------------------------------------------------------------- | | `UNKNOWN` | `unknown` | Falha não classificada | Não foi possível concluir a verificação. Tente novamente. | | `TOO_MUCH_MOVEMENT` | `tooMuchMovement` | Movimento excessivo | Mantenha o dispositivo firme por um momento durante a captura. | | `TOO_BRIGHT` | `tooBright` | Luz excessiva | Evite luz forte atrás de você ou reduza o brilho. | | `TOO_DARK` | `tooDark` | Pouca luz | Encontre um lugar mais claro. | | `LIGHTING_ISSUES` | `lightingIssues` | Iluminação inadequada | Certifique-se de que seu rosto esteja bem iluminado e sem reflexos. | | `MISALIGNED_FACE`, `FACE_NOT_FOUND` | `misalignedFace`, `faceNotFound` | Posição do rosto no guia | Segure a câmera frontal na altura dos olhos. | | `EYES_CLOSED`, `SUNGLASSES`, `EYEWEAR` | `eyesClosed`, `sunglasses`, `eyewear` | Área dos olhos não confirmada | Certifique-se de que seus olhos estejam visíveis. | | `FACE_TOO_FAR` | `faceTooFar` | Distância do rosto | Aproxime um pouco o rosto da câmera. | | `FACE_TOO_CLOSE` | `faceTooClose` | Distância do rosto | Afaste um pouco o rosto da câmera. | | `OBSCURED_FACE` | `obscuredFace` | Rosto coberto | Certifique-se de que nada fique entre você e a câmera. | | `MULTIPLE_FACES` | `multipleFaces` | Mais de um rosto | Certifique-se de que apenas seu rosto apareça na tela. | | `FRAMES_BLURRY` | `framesBlurry` | Imagem borrada | Não foi possível concluir a verificação. Tente novamente. | | `MOTION_ISSUE` | `motionIssue` | Inconsistência de movimento | Mantenha o telefone firme na altura dos olhos e encaixe seu rosto no oval. | | `BACKGROUND_ISSUE` | `backgroundIssue` | Fundo ou contraste | Não foi possível concluir a verificação. Tente novamente. | | `DEVICE_ISSUE` | `deviceIssue` | Dispositivo ou ambiente | Não foi possível concluir a verificação. Tente novamente. | | `DEVICE_RESTART` | `deviceRestart` | Reinício do dispositivo | Não foi possível concluir a verificação. Tente novamente. | | `SYSTEM_ERROR`, `REJECTED`, `USER_NOT_FOUND` | `systemError`, `rejected`, `userNotFound` | Erro do sistema | Não foi possível concluir a verificação. Tente novamente. | | `TIMEOUT` | `timeout` | Tempo limite atingido | Não foi possível concluir a verificação. Tente novamente. | | `PROCESSING_FAULT` | `processingFault` | Falha no processamento | Não foi possível concluir a verificação. Tente novamente. | ## Tipos de falha em detalhe ### Falha não classificada `UNKNOWN` **O que isso significa:** a sessão terminou sem aprovação, mas a análise não conseguiu atribuir um motivo específico. É um resultado abrangente: algo impediu uma decisão segura, sem dizer o quê. **Causas comuns:** vários pequenos fatores ao mesmo tempo (um pouco de movimento, iluminação irregular, o rosto levemente fora do centro), um resultado ambíguo em que a análise não reuniu evidências suficientes para decidir, dispositivos antigos ou de entrada com câmeras de menor qualidade, ou bloqueios de prevenção a fraudes. **Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.* **Comportamento:** nova tentativa. {% hint style="warning" %} Como a causa real é desconhecida, evite dicas específicas aqui. Orientações erradas, como "procure mais luz" quando o problema era movimento, tendem a causar novas falhas e frustração. E, como esse tipo também pode representar um bloqueio de segurança, a mensagem não deve sugerir nenhum motivo. {% endhint %} ### Movimento excessivo `TOO_MUCH_MOVEMENT` **O que isso significa:** o rosto ou o dispositivo se moveu demais durante a captura, e a sequência de imagens não pôde ser analisada de forma consistente. **Causas comuns:** o usuário caminhando ou dentro de um veículo em movimento, o telefone segurado com o braço estendido ou com uma só mão, ajustando a posição do telefone no meio da captura, ou movimentos de cabeça e fala durante a captura. **Mensagem recomendada:** *Mantenha o dispositivo firme por um momento durante a captura.* **Comportamento:** dica exibida após a tentativa. {% hint style="info" %} Como esta mensagem é exibida após a tentativa, ela deixa claro quando o usuário precisa ficar parado ("durante a captura"). {% endhint %} ### Luz excessiva `TOO_BRIGHT` **O que isso significa:** havia luz demais no ambiente ou no rosto para a análise. Durante a captura, a tela do telefone ilumina o rosto com cores. Quando a luz ambiente é forte demais, ela apaga esse efeito e a análise não consegue lê-lo. **Causas comuns:** luz solar direta no rosto ou na câmera, uma janela muito clara ou luz forte atrás do usuário, uma lâmpada forte bem acima da cabeça, ou brilho da tela baixo, inclusive no modo de economia de bateria. **Mensagem recomendada:** *Evite luz forte atrás de você ou reduza o brilho.* **Comportamento:** dica exibida após a tentativa. ### Pouca luz `TOO_DARK` **O que isso significa:** não havia luz suficiente no rosto para que seus traços fossem lidos com qualidade. **Causas comuns:** um ambiente mal iluminado ou um ambiente à noite com as luzes apagadas, a única fonte de luz atrás do usuário, o rosto iluminado apenas pela tela do telefone, ou a aba de um boné ou capuz fazendo sombra no rosto. **Mensagem recomendada:** *Encontre um lugar mais claro.* **Comportamento:** dica exibida após a tentativa. ### Iluminação inadequada `LIGHTING_ISSUES` **O que isso significa:** a iluminação atrapalhou a análise, mas o resultado não diz se havia luz demais ou de menos. Normalmente envolve luz irregular, sombras ou reflexos. **Causas comuns:** luz vindo de apenas um lado, deixando metade do rosto na sombra, reflexos fortes na pele ou nos óculos, luzes coloridas no ambiente (LED, TV, letreiros) ou a iluminação mudando durante a captura. **Mensagem recomendada:** *Certifique-se de que seu rosto esteja bem iluminado e sem reflexos.* **Comportamento:** dica exibida após a tentativa. {% hint style="info" %} **Observação:** A mensagem não diz se a intenção é clarear ou escurecer, porque o tipo não diz qual dos dois. {% endhint %} ### Posição do rosto no guia `MISALIGNED_FACE` `FACE_NOT_FOUND` **O que isso significa:** * `MISALIGNED_FACE`: o rosto foi encontrado, mas não está alinhado com o guia (oval) na tela. * `FACE_NOT_FOUND`: nenhum rosto foi encontrado na área de captura. **Causas comuns:** o telefone abaixo da altura do queixo, o rosto inclinado, de perfil ou deslocado para um lado do oval, o usuário olhando para outro ponto da tela, a câmera apontada para outro lugar ou a captura começando antes de o usuário estar posicionado, ou a lente coberta por um dedo, uma capa ou sujeira. **Mensagem recomendada:** *Segure a câmera frontal na altura dos olhos.* **Comportamento:** dica exibida após a tentativa. ### Área dos olhos não confirmada `EYES_CLOSED` `SUNGLASSES` `EYEWEAR` **O que isso significa:** a análise não conseguiu confirmar a área dos olhos. Na prática, os três tipos levam à mesma situação: os olhos não estavam visíveis com clareza suficiente. **Causas comuns:** piscar no momento da captura, semicerrar os olhos por causa da luz, olhar para baixo ou usar óculos de sol ou óculos de grau com reflexos fortes. Isso também pode acontecer sem óculos e com os olhos abertos, por causa de uma sombra ou de um reflexo ao redor dos olhos, do ângulo do telefone ou de uma imagem borrada. **Mensagem recomendada:** *Certifique-se de que seus olhos estejam visíveis.* **Comportamento:** dica neutra exibida após a tentativa. {% hint style="info" %} **Aviso:** A mensagem é neutra de propósito. Ela não diz "seus olhos estavam fechados" nem "remova seus ó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 errou. {% endhint %} ### Distância do rosto `FACE_TOO_FAR` `FACE_TOO_CLOSE` **O que isso significa:** o rosto estava longe demais (pequeno no oval) ou perto demais (ultrapassando o oval) para a análise. **Causas comuns:** o braço totalmente estendido ou o telefone apoiado longe do rosto (longe demais), ou o telefone muito perto, com o rosto cortado nas bordas. Estar perto demais é comum entre usuários com baixa visão, que aproximam o dispositivo para ler a tela. **Mensagem recomendada:** * `FACE_TOO_FAR`: *Aproxime um pouco o rosto da câmera.* * `FACE_TOO_CLOSE`: *Afaste um pouco o rosto da câmera.* **Comportamento:** dica exibida após a tentativa. ### Rosto coberto `OBSCURED_FACE` **O que isso significa:** parte do rosto estava coberta por um objeto, o que impediu uma análise completa. **Causas comuns:** uma máscara, cachecol ou gola alta cobrindo a boca e o queixo, uma mão tocando o rosto, cabelo ou franja sobre os olhos, um boné, chapéu ou capuz cobrindo a testa, ou um dedo ou capa cobrindo parte da lente. **Mensagem recomendada:** *Certifique-se de que nada fique entre você e a câmera.* **Comportamento:** dica exibida após a tentativa. ### Mais de um rosto `MULTIPLE_FACES` **O que isso significa:** mais de um rosto foi encontrado na imagem, e a análise não conseguiu ter certeza de qual 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, pôster ou TV com rostos ao fundo, ou o próprio reflexo do usuário em um espelho. **Mensagem recomendada:** *Certifique-se de que apenas seu rosto apareça na tela.* **Comportamento:** dica exibida após a tentativa. {% hint style="warning" %} A mensagem deve pedir que apenas o titular da conta apareça. Evite textos que incentivem ajuda de outra pessoa durante a captura. {% endhint %} ### Imagem borrada `FRAMES_BLURRY` **O que isso significa:** as imagens capturadas não estavam nítidas o suficiente para a análise. **Causas comuns:** uma lente da câmera frontal suja ou engordurada, uma película ou capa sobre a lente, foco automático que não se ajustou com o rosto muito perto, ou pouca luz combinada com movimento. **Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.* **Comportamento:** nova tentativa. ### Inconsistência de movimento `MOTION_ISSUE` **O que isso significa:** a sessão não foi aprovada porque o modelo não detectou movimento suficiente. Esse modelo avalia o quanto o usuário se move durante a captura e se o movimento parece o de uma pessoa real na frente da câmera. Diferente de `TOO_MUCH_MOVEMENT`, que significa movimento excessivo, `MOTION_ISSUE` significa que o movimento registrado não pareceu natural para o modelo, mesmo sem ser excessivo. Isso também pode significar que o dispositivo não tem sensor de movimento, ou que o sensor não pôde ser identificado. **Causas comuns:** o caso mais comum é o usuário mover o telefone para encaixar o rosto no oval, em vez de manter o dispositivo parado e ajustar a posição da cabeça. Ângulos extremos, como o telefone muito abaixo ou muito acima do rosto, e o rosto saindo do enquadramento durante a captura também podem causar isso. **Como orientar o usuário:** mantenha o telefone parado na altura dos olhos e mova apenas a cabeça para encaixar o rosto no oval. Na maioria dos casos, a próxima tentativa com essa orientação é aprovada. Sugerir outro dispositivo só faz sentido depois de várias falhas seguidas. **Mensagem recomendada:** * Primeira falha: *Mantenha o telefone firme na altura dos olhos e encaixe seu rosto no oval.* * Falhas repetidas: *Mantenha o telefone firme na altura dos olhos e encaixe seu rosto no oval. Se o problema continuar, reinicie o dispositivo ou tente outro.* **Comportamento:** primeira falha, nova tentativa. Falhas repetidas, sugira reiniciar ou trocar de dispositivo apenas como dica secundária. {% hint style="info" %} **Aviso:** Na primeira falha com esse tipo, peça apenas uma nova captura com o telefone parado. Não sugira mudar ou reiniciar o dispositivo de imediato. Como a causa mais comum é a forma como o telefone é segurado durante a captura, a maioria dos usuários é aprovada na próxima tentativa, no mesmo dispositivo. {% endhint %} ### Fundo ou contraste `BACKGROUND_ISSUE` **O que isso significa:** o fundo da imagem dificultou separar o rosto do ambiente. **Causas comuns:** uma parede com cor parecida com o tom da pele, um fundo muito claro com luz forte atrás do usuário, ou um fundo com muitos elementos, padrões ou movimento. **Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.* **Comportamento:** nova tentativa. ### Dispositivo ou ambiente `DEVICE_ISSUE` **O que isso significa:** esse tipo agrupa falhas de naturezas diferentes, relacionadas ao comportamento do usuário, ao ambiente ou ao próprio dispositivo. A avaliação inclui a qualidade da captura, as condições de iluminação, o contexto do dispositivo e o funcionamento da câmera. **Causas comuns:** baixa qualidade de captura, iluminação desfavorável, um problema na câmera (como a câmera estar sendo usada por outro app, ou uma falha momentânea), ou configurações do dispositivo fora do padrão, como um emulador, depuração ativa, jailbreak ou root. **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 continuar, reinicie o dispositivo ou tente outro.* **Comportamento:** primeira falha, nova tentativa. Falhas repetidas, sugira reiniciar ou trocar de dispositivo apenas como dica secundária. {% hint style="warning" %} Na primeira falha com esse tipo, peça apenas uma nova captura. Não sugira mudar ou reiniciar o dispositivo de imediato. Como esse tipo agrupa causas de naturezas diferentes, a mensagem deve permanecer genérica e não deve sugerir um motivo específico. {% endhint %} {% hint style="info" %} **Android:** compilações de depuração e apps instalados via ADB sempre retornam `DEVICE_ISSUE` no ambiente de produção. Consulte [Verificações de Segurança](/sdk-lite/sdk-lite-english-pt-br/configuracao/android/security-checks.md) antes de testar. {% endhint %} ### Reinício do dispositivo `DEVICE_RESTART` **O que isso significa:** o dispositivo está em um estado que costuma ser resolvido reiniciando-o. **Causas comuns:** a câmera ou outros recursos do dispositivo travaram após muito tempo sem reiniciar, superaquecimento ou pouca memória disponível. **Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.* **Comportamento:** nova tentativa. {% hint style="info" %} Para sua equipe de suporte: quando um usuário procura suporte após falhas repetidas com esse tipo, pedir para reiniciar o dispositivo geralmente resolve. {% endhint %} ### Erro do sistema `SYSTEM_ERROR` `REJECTED` `USER_NOT_FOUND` **O que isso significa:** um erro interno no processamento da análise, sem relação com o comportamento do usuário. **Causas comuns:** instabilidade momentânea ou uma falha de comunicação pontual entre os componentes que processam a análise. **Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.* **Comportamento:** nova tentativa. ### Tempo limite atingido `TIMEOUT` **O que isso significa:** a sessão ultrapassou o limite de tempo do sistema antes de ser concluída. **Causas comuns:** uma conexão lenta que impede o envio da captura a tempo, ou um atraso no processamento da análise. **Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.* **Comportamento:** nova tentativa. {% hint style="info" %} **iOS:** quando o usuário demora demais, o SDK não retorna essa falha. Em vez disso, ele retorna o `userTimeoutException` erro. Consulte [Tratamento de erros no iOS](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios/handling-errors.md#usertimeoutexception). {% endhint %} ### Falha no processamento `PROCESSING_FAULT` **O que isso significa:** a captura foi concluída, mas o processamento falhou no servidor. **Causas comuns:** um envio interrompido ou incompleto porque a conexão caiu, ou uma falha momentânea no serviço de análise. **Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.* **Comportamento:** nova tentativa. ## Repetições e investigação ### Permitindo novas tentativas * Permita pelo menos **duas** tentativas. Três é a prática recomendada. * 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 de forma independente. Um usuário legítimo pode falhar em uma tentativa e ser aprovado na seguinte em condições aparentemente iguais. Isso é o sistema funcionando como projetado. ### Ajudando os usuários a serem aprovados na primeira tentativa Mostre orientações curtas e visuais antes da captura. Essas dicas cobrem a maioria das falhas: * Segure o telefone na altura dos olhos e alinhe o rosto no oval. * Mova a cabeça, não o telefone, para alinhar o rosto com o oval. * Depois que o rosto estiver no oval, fique parado até a captura terminar. * Certifique-se de que o rosto esteja bem iluminado, sem luz forte atrás do usuário. * Mantenha todo o rosto visível, com os olhos abertos. * Evite capturar dentro de um veículo em movimento. ### Investigando casos * Observe 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. * Verifique os tipos de falha retornados em cada tentativa. * Compare cada caso com as orientações desta página antes de escalar. Quando você escalar um caso para o suporte da Certta, envie a data e a hora, a falha `tipo` e o `signedResponse` de **cada tentativa** do usuário. {% hint style="danger" %} Nunca envie o token móvel nem dados pessoais, como o número do documento do usuário ou imagens do rosto, em tickets de suporte ou logs. {% endhint %} --- # 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/handling-failures.md?ask=&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.