For the complete documentation index, see llms.txt. This page is also available as Markdown.

Android

The Face Liveness Lite Android SDK never throws exceptions into your code. When a run cannot start or cannot finish, the SDK delivers a LivenessLiteEvent.Error to the FaceLivenessLiteListener you passed to startLiveness().

CafFaceLivenessLite.instance.startLiveness { event ->
    if (event is LivenessLiteEvent.Error) {
        handleError(event)
    }
}

An error is always the last event of a run: after it, no other event is sent for that run. Events arrive on the main thread, so you can update the UI directly from the listener.

Where Errors Can Happen

Step
What can go wrong
Error type

startLiveness() call

configure() was not called, or another run is still active.

CONFIGURATION_EXCEPTION

Configuration check

Empty mobileToken or personId.

CONFIGURATION_EXCEPTION

Security check

The device is rooted, hooked or debugged.

SECURITY_EXCEPTION

Session creation

No connection, a server error, or a token not valid for this flow.

NETWORK_EXCEPTION or TOKEN_EXCEPTION

Capture

Camera permission denied, connection lost, server error or unsupported device.

CAMERA_PERMISSION, NETWORK_EXCEPTION, SERVER_EXCEPTION or UNSUPPORTED_DEVICE

Capture monitoring

A security threat appears while the camera is open.

SECURITY_EXCEPTION

Any step

An unexpected problem not mapped to a specific type.

GENERIC_EXCEPTION

configure() and prewarm() never report errors:

  • configure() only stores the configuration. It is checked when you call startLiveness().

  • prewarm() is an optimization. If it fails, startLiveness() creates the session again and reports any problem from there.

What the SDK Does When an Error Happens

The SDK cleans up on its own before delivering the error:

  • Closes the capture screen and the loading screen.

  • Stops the security monitoring.

  • Ends the run, so startLiveness() can be called again right away.

What Your App Should Do

  1. Log the details. Send type, description and cause to your logs or crash reporting tool.

  2. Show your own message. Map the type to a localized message. Do not show description or enum names to your users.

  3. Retry only when it can help. Each error type in Error Handling says whether a new attempt helps.

Category
Types

Integration

CONFIGURATION_EXCEPTION, TOKEN_EXCEPTION

User

CAMERA_PERMISSION

Temporary

NETWORK_EXCEPTION, SERVER_EXCEPTION

Device

SECURITY_EXCEPTION, UNSUPPORTED_DEVICE

Other

GENERIC_EXCEPTION, LIVENESS_EXCEPTION

LivenessLiteEvent.Cancelled is not an error: the user closed the capture screen. Go back to the previous screen without an error message.

Debugging

To see the SDK logs in Logcat while you investigate an error, enable logging:

Logs only appear when your app is debuggable. In release builds, this flag is ignored, so the SDK never logs sensitive data such as the token in production.

Next Steps

For the error model and every error type in detail: Error Handling

Last updated