> 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/backend/handling-failures.md).

# Tratamento de falhas

Uma falha é uma tentativa de liveness que foi processada, mas não terminou com uma face viva: o resultado informa que a face não está viva, ou a tentativa não foi concluída com um veredito. A chamada da API em si foi bem-sucedida. As solicitações às quais a API não pôde responder são abordadas em [Tratamento de Erros](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/backend/handling-errors.md).

## Resultados em resumo

Toda chamada bem-sucedida para `GET /v1/faces/liveness/attempts/{attemptId}/await` retorna um dos três desfechos abaixo:

| Desfecho         | `status`    | `isAlive` | O que significa                                                                                       | Próxima etapa                                                                                               |
| ---------------- | ----------- | --------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Viva**         | `COMPLETED` | `true`    | A verificação foi concluída e a face está viva.                                                       | Continue a jornada. Opcionalmente, verifique os [sinais de qualidade da captura](#capture-quality-signals). |
| **Não viva**     | `COMPLETED` | `false`   | A verificação foi concluída e a face não está viva.                                                   | Não aprove a tentativa. Aplique sua política de repetição.                                                  |
| **Não concluiu** | `FAILED`    | —         | A tentativa não foi processada até um veredito. Nenhum `isAlive`, `sinais` ou imagens são retornadas. | Não aprove a tentativa. Ofereça ao usuário uma nova captura, seguindo sua política de repetição.            |

{% hint style="warning" %}
Decida somente com base no resultado que seu backend recuperou. Nunca aprove uma tentativa de liveness com base no que o app informa, e nunca trate um campo ausente `isAlive` como `true`.
{% endhint %}

### Não viva não é o mesmo que

`COMPLETED` com `isAlive: false` é uma **verificação concluída**: há um veredito, e o veredito é negativo. `FAILED` significa que há **nenhum veredito** de forma alguma. Trate-os separadamente nos seus logs e métricas: eles têm causas diferentes e próximas etapas diferentes.

## Oferecendo uma nova tentativa

{% stepper %}
{% step %}

## Solicite um novo token de sessão

Seu backend solicita um novo token de sessão e armazena o novo `tokenId` ([Configuração — etapa 1](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md)).
{% endstep %}

{% step %}

## Inicie o SDK novamente

O app inicia o SDK novamente com o novo `sessionToken`.
{% endstep %}

{% step %}

## Valide e recupere o resultado

Seu backend valida o novo `signedResponse` e recupera o novo resultado.
{% endstep %}
{% endstepper %}

Não reutilize um `sessionToken`, `tokenId` ou `livenessAttemptId` de uma tentativa anterior. Chamar o endpoint de resultado novamente para o mesmo `livenessAttemptId` retorna o mesmo resultado.

Defina um limite para novas tentativas na sua política de repetição. Quando o usuário alcançá-lo, encaminhe-o para outro caminho de verificação.

## Falhas relatadas pelo SDK

Quando a captura é executada, mas não é aprovada, o SDK relata uma falha ao app com um tipo de falha `tipo` que ajuda a orientar o usuário na próxima tentativa:

* iOS: `didFinishWithFailure(type:description:signedResponse:)` — veja [Referência do Resultado](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/result-reference.md).
* Android: `LivenessLiteEvent.Failure(signedResponse, type, description)` — veja [Iniciando o Fluxo de Liveness](/sdk-lite/sdk-lite-english-pt-br/configuracao/android/configuration/starting-liveness-flow.md).

Os tipos de falha e a mensagem recomendada ao usuário para cada um estão em [Motivos da Falha e Orientações ao Usuário](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/handling-failures.md).

Use a falha `tipo` no app para exibir orientação ao usuário. No seu backend, trate-o como qualquer outra tentativa: quando um `signedResponse` vier com a falha, valide-o e recupere o resultado conforme descrito em [Configuração](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md). O resultado que seu backend recupera é o desfecho da tentativa.

Se nenhum `signedResponse` vier com a falha, não há tentativa a recuperar. Ofereça uma nova tentativa.

## Sinais de qualidade da captura

Quando `status` está `COMPLETED`, `sinais` o resultado pode incluir um bloco com dois indicadores de qualidade da captura:

| Sinal                 | `true` significa                                               | Quando está `false`                                                         |
| --------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `isImageQualityOk`    | A imagem tem nitidez, iluminação e posição do rosto adequadas. | A imagem pode ser uma referência ruim para autenticação facial posterior.   |
| `isFaceConsistencyOk` | Havia apenas um rosto, o mesmo, durante toda a captura.        | Mais de um rosto, ou uma mudança de rosto, foi observada durante a captura. |

Os sinais são **informativos**. Certta não altera `isAlive` com base neles. A decisão de solicitar uma nova captura é sua, de acordo com sua própria política.

Isso é mais importante quando você armazena a selfie aprovada como imagem de referência, por exemplo, para autenticação facial posterior. Uma imagem de referência ruim aumenta falhas e atritos nas autenticações que seguem. Com os sinais, você pode pedir uma nova selfie **antes de** você armazená-la.

{% hint style="info" %}
**A ausência de um `sinais` bloco não é uma falha.** `sinais` é omitido quando `status` está `FAILED` e para tentativas capturadas antes de os sinais ficarem disponíveis. Quando ele estiver ausente, trate-o como "sem informação de qualidade" e decida apenas a partir de `isAlive` sozinho. Não interprete um bloco ausente como `false`.
{% endhint %}

### Decisão sugerida

| `isAlive` | `sinais`         | Tratamento sugerido                                                                             |
| --------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| `true`    | Ambos `true`     | Aprove e, se aplicável, armazene a imagem como referência.                                      |
| `true`    | Qualquer `false` | Aprove o liveness. Considere pedir uma nova selfie antes de armazenar a imagem como referência. |
| `true`    | Ausente          | Aprove, decidindo a partir de `isAlive` sozinho.                                                |
| `false`   | Qualquer         | Não aprove. Aplique sua política de repetição.                                                  |


---

# 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/backend/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.