> 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/flutter/face-liveness/handling-failures.md).

# Tratamento de Falhas

Referência para o tratamento de falhas do Face Liveness no Flutter. Aprenda sobre os tipos de CerttaLivenessFailure, valores de causa e como mapear falhas para orientações claras ao usuário.

{% hint style="warning" %}
Este guia aborda **caf\_sdk 2.4.0** e superiores (Certta DevX). Para a versão anterior `CafSdk` fluxo sequencial, consulte a [documentação legada](https://docs.caf.io/caf-sdk/flutter/getting-started-with-the-sdk).
{% endhint %}

Quando uma verificação de vivacidade falha, o SDK emite `CerttaLivenessEvent.failed` com um `CerttaLivenessFailure` objeto. Este objeto contém um `causa` parâmetro (um código estável para lógica de mapeamento) e, para falhas de reconhecimento, um `description` campo com texto exibido ao usuário.

Entender e lidar com esses campos é fundamental para fornecer feedback claro e acionável, para que os usuários possam corrigir o problema e tentar novamente.

### Os modelos de falha

Tanto as falhas de captura quanto as de reconhecimento compartilham o mesmo `CerttaLivenessFailure` tipo. Use `type` para distingui-las:

| `type`                   | Significado                                                                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ImageCaptureFailure`    | A captura de imagem falhou. Nenhuma imagem assinada (`response`) está disponível.                                                                                          |
| `FaceRecognitionFailure` | A captura foi bem-sucedida, mas o reconhecimento ou a autenticação falharam. `response` contém o payload assinado. `description` fornece uma mensagem legível por humanos. |

Para `FaceRecognitionFailure`, `causa` é normalizado para maiúsculas pelo plugin do Flutter. Use `causa` para lógica condicional e `description` (ou sua própria versão localizada) para mensagens exibidas aos usuários finais.

{% 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 %}

### Ao usar `causa` e `description`

A `causa` o parâmetro retorna uma string constante estável (por exemplo `"TOO_DARK"` ou `"FACE_TOO_FAR"`). Não exiba `causa` diretamente aos usuários finais.

Para `FaceRecognitionFailure`, prefira `description` como fallback quando você não mantiver um mapeamento personalizado. Caso contrário, mapeie `causa` para uma mensagem localizada e amigável ao usuário na sua interface.

#### Causas de falha disponíveis

Ao usar o [iProov](https://github.com/iProov/android) provider, se a captura for bem-sucedida, mas o mecanismo falhar ao autenticar ou processar o rosto, o SDK retorna um `FaceRecognitionFailure`.

Possíveis `causa` valores:

|        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 cobrem os olhos       |
|   `OBSCURED_FACE`   | Obstrução parcial do rosto       |
|    `EYES_CLOSED`    | Olhos fechados durante a captura |
|   `MULTIPLE_FACES`  | Vários rostos detectados         |
|  `BACKGROUND_ISSUE` | 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            |

A documentação anterior do CafSdk também indicava quais causas se aplicam aos provedores GPA vs LA. Considere a tabela acima como o conjunto completo de identificadores que você pode receber; mapeie valores desconhecidos para uma mensagem genérica de nova tentativa.

### Exemplo de implementação

```dart
String messageForLivenessFailure(CerttaLivenessFailure failure) {
  if (failure.type == 'ImageCaptureFailure') {
    debugPrint('A captura falhou antes de chegar ao servidor.');
  } else if (failure.type == 'FaceRecognitionFailure') {
    debugPrint('O servidor rejeitou a captura. Resposta: ${failure.response}');
    if (failure.description != null && failure.description!.isNotEmpty) {
      return failure.description!;
    }
  }

  switch (failure.cause) {
    case 'TOO_DARK':
      return "Está um pouco escuro. Por favor, vá para um ambiente mais iluminado.";
    case 'FACE_TOO_FAR':
      return 'Por favor, aproxime o celular do seu rosto.';
    case 'EYES_CLOSED':
      return 'Por favor, mantenha os olhos abertos e olhe diretamente para a câmera.';
    case 'MULTIPLE_FACES':
      return 'Certifique-se de ser a única pessoa no enquadramento.';
    case 'TIMEOUT':
      return 'O tempo acabou. Por favor, tente novamente quando estiver pronto.';
    case 'REJECTED':
    case 'FACE_AUTHENTICATION':
      return "Não foi possível verificar seu rosto. Tente novamente.";
    default:
      return 'Ocorreu um erro inesperado (${failure.cause}). Tente novamente.';
  }
}
```


---

# 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/caf-sdk/caf-sdk-pt-br/flutter/face-liveness/handling-failures.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.