> 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/android/getting-started-with-the-sdk/handling-failures.md).

# Handling Failures

{% hint style="warning" %}
This guide covers version 7.14.0 and above. For versions below 7.14.0, please see the [legacy documentation](https://docs.caf.io/caf-sdk/android/getting-started-with-the-sdk-1).
{% endhint %}

When a liveness check fails, the SDK returns a `LivenessFailure` object. This object contains a `cause` parameter, which is a string identifier that tells you exactly why the process was unsuccessful.

Understanding and handling the `cause` parameter is critical for providing clear, actionable feedback to your users so they can correct the issue and try again.

### The Failure Models

The SDK uses a sealed class hierarchy to categorize failures. Both capture-level and recognition-level failures inherit from the base `LivenessFailure` class, ensuring you can always access the `cause` string.

{% code title="LivenessFailure.kt" %}

```kotlin
public sealed class LivenessFailure(public open val cause: String) {
    
    // Triggered when the image capture process fails. No image (response) available
    public data class ImageCaptureFailure(override val cause: String) : LivenessFailure(cause)
    
    // Triggered when fails to recognize or authenticate the face.
    public data class FaceRecognitionFailure(
        public val response: String, 
        override val cause: String
    ) : LivenessFailure(cause)
}
```

{% endcode %}

{% hint style="warning" %}
Ensure the JWT response is evaluated on the backend. This process must include validating the token's signature and verifying the `isAlive` and `isMatch` fields. Do not perform these validations on the client side.
{% endhint %}

### Using the `cause` Parameter

The `cause` parameter returns a raw constant string (e.g., `"TOO_DARK"` or `"FACE_TOO_FAR"`).

Best Practice: Do not display these raw strings directly to your end-users. Instead, intercept the `cause` string and map it to a user-friendly, localized message in your app's UI to guide them on how to fix the problem.

#### Available Failure Causes

When using the [Iproov](https://github.com/iProov/android) provider, if the image capture is successful but the engine fails to authenticate or process the face, the SDK returns a `FaceRecognitionFailure`.

Below is the list of possible `cause` values returned specifically during this phase:

|        Cause        | Description                |
| :-----------------: | -------------------------- |
|      `UNKNOWN`      | Generic failure            |
| `TOO_MUCH_MOVEMENT` | Excessive head motion      |
|     `TOO_BRIGHT`    | Over-illumination          |
|      `TOO_DARK`     | Low light conditions       |
|  `MISALIGNED_FACE`  | Face alignment failure     |
|    `FACE_TOO_FAR`   | Face too distant           |
|   `FACE_TOO_CLOSE`  | Face too close             |
|     `SUNGLASSES`    | Eye-obscuring eyewear      |
|   `OBSCURED_FACE`   | Partial face obstruction   |
|    `EYES_CLOSED`    | Closed eyes during capture |
|   `MULTIPLE_FACES`  | Multiple faces detected    |
|  `BACKGROUND_ISSUE` | Unsuitable background      |
|    `DEVICE_ISSUE`   | Incompatible device        |
|      `EYEWEAR`      | Eyewear detected           |
|   `FACE_NOT_FOUND`  | Face detection failure     |
|   `FRAMES_BLURRY`   | Blurry frames detected     |
|    `MOTION_ISSUE`   | Device motion error        |
|  `LIGHTING_ISSUES`  | Poor lighting conditions   |
|      `REJECTED`     | Transaction rejected       |
|    `SYSTEM_ERROR`   | Internal system error      |
|      `TIMEOUT`      | Session timeout            |
|   `USER_NOT_FOUND`  | User lookup failure        |
|   `DEVICE_RESTART`  | Device state error         |
|  `PROCESSING_FAULT` | Processing error           |

### Example Implementation

Here is an example of how you might handle a `LivenessFailure` and map the `cause` parameter to helpful user guidance:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
fun handleLivenessError(failure: LivenessFailure) {
    // 1. You can check the specific type of failure if needed
    when (failure) {
        is LivenessFailure.ImageCaptureFailure -> {
            println("Capture failed before reaching the server.")
        }
        is LivenessFailure.FaceRecognitionFailure -> {
            println("Server rejected the capture. Response: ${failure.response}")
        }
    }

    // 2. Map the 'cause' to a user-friendly message
    val userMessage = when (failure.cause) {
        "TOO_DARK" -> "It's a bit too dark. Please move to a brighter room."
        "FACE_TOO_FAR" -> "Please bring the phone closer to your face."
        "EYES_CLOSED" -> "Please keep your eyes open and look directly at the camera."
        "MULTIPLE_FACES" -> "Ensure you are the only one in the frame."
        "TIMEOUT" -> "Time ran out. Please try again when you are ready."
        "REJECTED", "FACE_AUTHENTICATION" -> "We couldn't verify your face. Please try again."
        //...
        else -> "An unexpected error occurred (${failure.cause}). Please try again."
    }

    // 3. Display the message in your UI
    showErrorDialog(userMessage)
}
```

{% endtab %}

{% tab title="Java" %}
{% code title="" %}

```java
public void handleLivenessError(LivenessFailure failure) {
    // 1. You can check the specific type of failure if needed
    if (failure instanceof LivenessFailure.ImageCaptureFailure) {
        System.out.println("Capture failed before reaching the server.");
    } else if (failure instanceof LivenessFailure.FaceRecognitionFailure) {
        // Cast to access specific properties like response
        LivenessFailure.FaceRecognitionFailure recognitionFailure = 
            (LivenessFailure.FaceRecognitionFailure) failure;
        System.out.println("Server rejected the capture. Response: " + recognitionFailure.getResponse());
    }

    // 2. Map the 'cause' to a user-friendly message
    String userMessage;
    String cause = failure.getCause();

    switch (cause) {
        case "TOO_DARK":
            userMessage = "It's a bit too dark. Please move to a brighter room.";
            break;
        case "FACE_TOO_FAR":
            userMessage = "Please bring the phone closer to your face.";
            break;
        case "EYES_CLOSED":
            userMessage = "Please keep your eyes open and look directly at the camera.";
            break;
        case "MULTIPLE_FACES":
            userMessage = "Ensure you are the only one in the frame.";
            break;
        case "TIMEOUT":
            userMessage = "Time ran out. Please try again when you are ready.";
            break;
        case "REJECTED":
        case "FACE_AUTHENTICATION":
            userMessage = "We couldn't verify your face. Please try again.";
            break;
        //...
        default:
            userMessage = "An unexpected error occurred (" + cause + "). Please try again.";
            break;
    }

    // 3. Display the message in your UI
    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/android/getting-started-with-the-sdk/handling-failures.md?ask=<question>&goal=<endgoal>
```

`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.