> 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-erros/ios/handling-errors.md). # Tratamento de Erros Quando o processo de vivacidade não pode ser concluído, o SDK chama `didFinishWithError(type:description:)` no seu `CafFaceLivenessLiteDelegate`. O `parâmetro` é um `CafErrorType` valor que informa por que o processo foi interrompido. Esta página explica o que cada resultado significa, quando se espera que cada erro ocorra e como orientar o usuário na próxima tentativa. ## Resultados em resumo Cada execução de vivacidade termina com exatamente um dos quatro callbacks de delegate abaixo. Trate e reporte-os separadamente: eles têm causas diferentes e próximos passos diferentes. | Resultado | Callback | O que significa | `signedResponse` | Próximo passo para o usuário | | ------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Sucesso** | `didFinishWithSuccess(livenessResult:)` | A captura foi concluída. | Sim | Continue a jornada. Seu backend recupera o resultado final de vivacidade com o `signedResponse`. | | **Falha** | `didFinishWithFailure(type:description:signedResponse:)` | A captura foi executada e avaliada, mas não foi aprovada. Isso não é um julgamento sobre a pessoa. | Sim | Exiba orientações com base na falha `parâmetro` e ofereça uma nova tentativa. | | **Erro** | `didFinishWithError(type:description:)` | O processo não pôde ser executado ou não pôde ser concluído. Nenhuma captura foi avaliada. | Não | Depende do erro `parâmetro`. Veja [Tipos de erro em resumo](#error-types-at-a-glance). | | **Cancelado** | `cancelled()` | O usuário fechou a tela de captura. | Não | Volte para a tela anterior sem exibir uma mensagem de erro. Permita que o usuário comece novamente quando estiver pronto. | {% hint style="warning" %} Nunca decida o resultado de vivacidade no cliente. Seu backend valida o `signedResponse` (assinatura e `tokenId`) e então recupera o resultado final com o `livenessAttemptId` que ele carrega. Veja [Configuração do backend](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md). {% endhint %} ### Falhas são orientações, não um diagnóstico Cada tentativa é avaliada individualmente. Duas tentativas da mesma pessoa com um minuto de diferença são dois conjuntos de evidências diferentes, então um usuário legítimo pode falhar em uma tentativa e passar na seguinte em condições aparentemente iguais. É assim que o sistema funciona como projetado. A falha `parâmetro` responde *“o que é mais provável ajudar este usuário a passar na próxima tentativa?”*, e não *“o que havia de errado com esta imagem?”*. Tenha em mente que: * Um código de falha pode ser retornado mesmo quando a imagem capturada parece nítida e bem iluminada. A decisão considera a captura como um todo, não apenas o frame final. * As orientações são intencionalmente genéricas. Mensagens consistentes e não reveladoras ajudam usuários legítimos sem dizer a um invasor o que mudar. * `motionIssue` e `deviceIssue` costumam ser resolvidos na próxima tentativa no mesmo dispositivo. Peça ao usuário que alinhe o rosto no oval, fique parado e encontre uma iluminação melhor. Sugira um dispositivo diferente apenas como alternativa, depois de várias tentativas. Os tipos de falha e a mensagem recomendada para cada um estão em [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). ## O callback de erro ```swift public protocol CafFaceLivenessLiteDelegate: AnyObject { // ... func didFinishWithError(type: CafErrorType, description: String) } ``` | Parâmetro | Descrição | | ------------- | ---------------------------------------------------------------- | | `parâmetro` | O `CafErrorType` que informa por que o processo foi interrompido | | `description` | Descrição técnica do erro, destinada aos seus logs | Um erro sempre encerra a execução de vivacidade, e nenhum `signedResponse` é retornado. Você pode chamar `startSDK(viewController:)` novamente logo após recebê-lo, com a configuração já passada para `setup`. Chamar `startSDK` enquanto uma captura ainda está em andamento não reporta um erro: a chamada é ignorada e nenhum método de delegate é chamado. Aguarde a execução atual terminar com um dos callbacks acima antes de iniciar uma nova. ## Usando o `parâmetro` parâmetro {% hint style="info" %} **Boa prática:** não exiba o nome cru do enum nem o `description` para os usuários finais. Mapeie o `parâmetro` para uma mensagem localizada no seu app e registre o `description` para que sua equipe possa investigar. O `description` é texto técnico que pode mudar entre versões, então não o analise nem crie lógica com base nele. {% endhint %} Alguns erros podem ser resolvidos pelo usuário, por exemplo concedendo a permissão da câmera ou reconectando à internet. Outros apontam para um problema de integração, como iniciar antes de `setup`, e precisam ser corrigidos no seu app ou na configuração da conta. {% hint style="warning" %} Nunca diga ao usuário qual verificação de segurança falhou, nem mostre detalhes técnicos como dados de certificado, endereços internos ou rastreamentos de pilha. Essas informações ajudam quem está tentando burlar a jornada. {% endhint %} ## Tipos de erro em resumo | Tipo | Categoria | O usuário pode tentar novamente? | Mensagem recomendada | | ------------------------------- | ------------------------ | ---------------------------------- | -------------------------------------------------------------------- | | `invalidOptionsException` | Integração | Não | Não conseguimos concluir a verificação. | | `tokenException` | Integração | Sim, com um novo token | Não conseguimos concluir a verificação. Tente novamente. | | `invalidResponseException` | Integração | Sim | Não conseguimos concluir a verificação. Tente novamente. | | `cameraPermission` | Usuário e ambiente | Sim, após conceder acesso | Permita o acesso à câmera para continuar. | | `networkException` | Usuário e ambiente | Sim | Sem conexão. Verifique sua internet e tente novamente. | | `serverException` | Usuário e ambiente | Sim | Não conseguimos concluir a verificação. Tente novamente. | | `userTimeoutException` | Usuário e ambiente | Sim | Não conseguimos concluir a verificação. Tente novamente. | | `captureAlreadyActiveException` | Usuário e ambiente | Sim, após a captura atual terminar | Você já tem uma verificação em andamento. Feche-a e tente novamente. | | `unsupportedDevice` | Usuário e ambiente | Não | Não conseguimos concluir a verificação. | | `securityException` | Segurança do dispositivo | Sim | Não conseguimos concluir a verificação. Tente novamente. | | `unexpectedErrorException` | Outro | Sim | Não conseguimos concluir a verificação. Tente novamente. | ### Erros de integração Esses erros geralmente apontam para um problema na integração entre seu app e o SDK, e não para algo que o usuário possa resolver mudando a forma como faz a captura. #### `invalidOptionsException` O SDK não pôde iniciar com a configuração atual. Isso acontece quando: * `startSDK` foi chamado antes de `setup`. * O SDK não conseguiu construir o endereço do serviço de captura a partir da configuração da sessão. **Mensagem recomendada:** *Não conseguimos concluir a verificação.* **O que fazer:** não ofereça uma nova tentativa. Encaminhe o usuário para o suporte ou para outro canal. No seu app, chame `setup(mobileToken:personId:…)` antes de `startSDK`. Se `setup` foi chamado e o erro persistir, entre em contato com o suporte da CAF com o `description`. {% hint style="info" %} Uma nova tentativa não muda o resultado. Esse erro não deve ser frequente em produção, então monitore-o e configure um alerta quando acontecer. {% endhint %} #### `tokenException` A sessão não pôde ser autorizada com o `mobileToken`. Isso acontece quando: * O token expirou, por exemplo porque foi criado muito antes do uso ou reutilizado de uma sessão anterior. * O token pertence a outro ambiente. * A conta por trás do token não está habilitada para o fluxo assíncrono do Face Liveness Lite. * A sessão foi criada sem os dados que a captura precisa para iniciar, ou sem o `signedResponse`. **Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.* **O que fazer:** ofereça uma nova tentativa com um novo token. Se o erro persistir com tokens novos, verifique a configuração do token com a equipe da sua conta CAF. {% hint style="info" %} Crie o token imediatamente antes de abrir o SDK e crie um novo para cada nova tentativa. {% endhint %} #### `invalidResponseException` A sessão foi criada sem o identificador da tentativa de vivacidade, então a captura não pôde ser registrada. O SDK para antes de submeter o usuário a uma captura. **Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.* **O que fazer:** permita que o usuário tente novamente. Se continuar acontecendo, entre em contato com o suporte da CAF com o `description`. ### Erros de usuário e ambiente Esses erros dependem do usuário, do dispositivo ou da rede. Exiba uma mensagem útil e permita que o usuário tente novamente quando fizer sentido. #### `cameraPermission` O usuário negou o acesso à câmera. `startSDK` verifica a permissão antes de qualquer solicitação de rede e mostra o prompt do sistema se o usuário ainda não tiver decidido. Esse erro também pode ser reportado durante a captura. Causas comuns: * O usuário negou o acesso quando foi solicitada a permissão. * A permissão foi negada anteriormente. O sistema não pergunta novamente. * A permissão foi revogada em Ajustes ou bloqueada por restrições do dispositivo, como Tempo de Uso, controles parentais ou gerenciamento corporativo do dispositivo. **Mensagem recomendada:** *Permita o acesso à câmera para continuar.* **O que fazer:** mostre uma tela específica com um botão que abre as configurações do app e, em seguida, chame `startSDK` novamente. {% hint style="info" %} Como o sistema não mostra a solicitação de permissão novamente, o botão deve abrir diretamente as configurações do app em vez de apenas tentar de novo. {% endhint %} #### `networkException` A conexão caiu **durante a captura**. **Mensagem recomendada:** *Sem conexão. Verifique sua internet e tente novamente.* **O que fazer:** mostre uma tela de conexão com um botão para tentar novamente. {% hint style="info" %} `networkException` cobre apenas a captura em si. Problemas de conexão enquanto o SDK ainda está criando a sessão, antes de a câmera abrir, são reportados como `serverException`. {% endhint %} #### `serverException` O serviço de vivacidade não pôde concluir a solicitação. Isso acontece quando: * A sessão não pôde ser criada: sem conexão, com timeout ou com uma resposta inválida ou ilegível. * A sessão aponta para uma configuração de captura que este SDK não suporta. * O serviço reportou um erro durante a captura. **Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.* **O que fazer:** permita que o usuário tente novamente. Se continuar acontecendo, entre em contato com o suporte da CAF. {% hint style="warning" %} A descrição técnica desse erro pode conter detalhes de certificado, endereços internos ou rastreamentos de pilha. Nunca a mostre ao usuário. {% endhint %} #### `userTimeoutException` O usuário não concluiu a captura dentro do limite de tempo da sessão. Causas comuns: o usuário demorou demais para iniciar ou finalizar a captura, ou o app foi para segundo plano no meio da sessão (uma chamada recebida, alternar entre apps, bloquear a tela). **Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.* **O que fazer:** ofereça uma nova tentativa e mostre primeiro uma orientação curta de captura. Veja [Ajudando usuários a passar na primeira tentativa](#helping-users-pass-on-the-first-attempt). #### `captureAlreadyActiveException` Outra captura já estava em andamento quando esta tentou começar, por exemplo após um duplo toque no botão de iniciar ou ao reabrir a tela de verificação antes de a anterior fechar. **Mensagem recomendada:** *Você já tem uma verificação em andamento. Feche-a e tente novamente.* **O que fazer:** aguarde a captura em andamento terminar antes de iniciar uma nova. Desative seu botão de iniciar após o primeiro toque: em alguns casos, uma segunda solicitação de início é simplesmente ignorada, sem callback. #### `unsupportedDevice` O dispositivo não consegue executar a captura. Isso acontece quando o dispositivo não atende aos requisitos de captura ou quando o SDK não conseguiu armazenar as credenciais com segurança no dispositivo. **Mensagem recomendada:** *Não conseguimos concluir a verificação.* **O que fazer:** não ofereça uma nova tentativa. Direcione o usuário para outro dispositivo ou outro caminho de verificação. Veja [Requisitos](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/requirements.md). ### Erros de segurança do dispositivo #### `securityException` `enableSecurity` é `true` e o SDK identificou um risco no ambiente do dispositivo ou do app, antes ou durante a captura. Veja [Verificações de segurança](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/security-checks.md). **Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.* **O que fazer:** permita que o usuário tente novamente, com uma mensagem genérica. As verificações são executadas novamente em cada `startSDK`, então o mesmo ambiente retorna o mesmo erro até que a condição desapareça. Se continuar acontecendo, direcione o usuário para outro caminho de verificação. {% hint style="warning" %} Nunca diga ao usuário qual verificação falhou, porque isso ensina como burlar a proteção. Se o volume for relevante entre usuários legítimos, analise os logs junto com a CAF. {% endhint %} ### Outros erros #### `unexpectedErrorException` Ocorreu um erro inesperado durante a captura. **Mensagem recomendada:** *Não conseguimos concluir a verificação. Tente novamente.* **O que fazer:** permita que o usuário tente novamente. Registre o tipo, o `description`, a versão do SDK (`CafFaceLivenessLiteSDK.getVersion()`), o modelo do dispositivo e a versão do iOS, e compartilhe-os com o suporte da CAF se continuar acontecendo. {% hint style="info" %} `CafErrorType` é compartilhado com outros SDKs da CAF e declara mais casos do que o CafFaceLivenessLite retorna. Quando você `fizer um switch` sobre ele, adicione um `default` em vez de tratar todos os casos. Veja [Referência de resultado](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/result-reference.md). {% endhint %} ## Verificações de segurança do dispositivo Quando `enableSecurity` é `true` (o padrão), o SDK verifica a integridade do dispositivo e do ambiente do app antes e durante a captura, e reporta `securityException` quando identifica um risco. A própria decisão de vivacidade também executa suas próprias verificações de ataque no servidor, que chegam ao seu app como uma falha com uma `signedResponse`. Veja [Verificações de segurança](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/security-checks.md) para entender como as duas camadas funcionam, a matriz de configuração e como testar sua integração. ## Tentativas 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** juntamente 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. ### Ajudando usuários a passar na primeira tentativa Exiba orientações curtas e visuais antes da captura. Estas 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. * Quando 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 de dispositivo, versão do iOS e versão do SDK. `CafFaceLivenessLiteSDK.getVersion()` retorna a versão do SDK. * Verifique os tipos de erro e de falha retornados para cada tentativa. * Compare cada caso com as orientações desta página antes de escalar. Quando você escalar um caso para o suporte da CAF, envie para **cada tentativa** do usuário: * Data e hora da tentativa. * Para erros: o `parâmetro` e o `description`. * Para falhas: o `parâmetro` e o `signedResponse`. {% hint style="danger" %} Nunca envie o `mobileToken` ou dados pessoais, como o número do documento do usuário ou imagens do rosto, em chamados de suporte ou logs. {% endhint %} ## Exemplo de implementação Aqui está um exemplo de como você pode tratar `didFinishWithError` no seu delegate: ```swift import CafFaceLivenessLite extension YourViewController: CafFaceLivenessLiteDelegate { func didFinishWithError(type: CafErrorType, description: String) { // 1. Registre os detalhes técnicos para sua equipe (nunca registre o mobileToken ou personId) print("Liveness error: type=\(type.rawValue) description=\(description)") // 2. Alguns erros não podem ser resolvidos tentando novamente switch type { case .invalidOptionsException, .unsupportedDevice: routeToAlternativeVerification() return default: break } // 3. Mapeie o 'type' para uma mensagem amigável ao usuário let userMessage: String switch type { case .cameraPermission: userMessage = "Permita o acesso à câmera para continuar." case .networkException: userMessage = "Sem conexão. Verifique sua internet e tente novamente." case .captureAlreadyActiveException: userMessage = "Você já tem uma verificação em andamento. Feche-a e tente novamente." default: userMessage = "Não conseguimos concluir a verificação. Tente novamente." } // 4. Exiba a mensagem na sua interface showErrorDialog(userMessage) } // didFinishWithSuccess, didFinishWithFailure, cancelled, loading e loaded // são abordados na página de Ciclo de Vida do SDK. } ``` --- # 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-erros/ios/handling-errors.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.