Handling Failures

Reference for Certta Liveness delegate events, blocking errors, and failure mapping on iOS, including success handling, diagnostics, and UI guidance.

This guide covers version 7.0.0 and above. For versions below 7.0.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.

---

Delegate callbacks (CerttaLivenessDelegate)

Delegate	Meaning
didFail(_:)	Business failure: the flow completed, but the outcome was not accepted (LivenessFailure).

---

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:

Stable cause values

cause	Hint
unknown	Unclassified
too_much_movement	Excessive head movement
too_bright, too_dark, lighting_issues	Lighting
misaligned_face	Not aligned with guide
eyes_closed	Eyes closed
face_too_far, face_too_close	Distance
sunglasses, eyewear	Glasses
obscured_face	Face covered
multiple_faces	More than one face
face_not_found	No face in region
frames_blurry	Too blurry
motion_issue	Motion
background_issue	Background / contrast
device_issue, device_restart	Device
system_error	System
rejected, timeout, user_not_found, processing_fault	Transaction / server

---

Example Implementation

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

func mapFailureToUX(_ failure: LivenessFailure) -> (code: String, message: String) {
    switch failure {
    case .imageCaptureFailure(let text):
        return ("image_capture", text)
    case .faceRecognitionFailure(_, let cause):
        let code = cause.lowercased()
        let message = localizedHint(forCause: code) ?? "Verification failed. Please try again."
        return (code, message)
    }
}

private func localizedHint(forCause cause: String) -> String? {
    switch cause {
    case "too_dark", "too_bright", "lighting_issues":
        return "Improve lighting and try again."
    case "multiple_faces":
        return "Only one person should be in the camera."
    case "timeout":
        return "Time ran out. Please try again."
    default:
        return nil
    }
}