Handling Failures

Reference for Android Face Liveness failure handling. Learn LivenessFailure types, cause values, provider-specific errors, and how to map failures to clear user guidance.

This guide covers version 7.14.0 and above. For versions below 7.14.0, please see the legacy documentation.

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.

LivenessFailure.kt

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)
}

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.

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 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:

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)
}

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);
}