> 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/failure-handling/mobile.md).

# Mobile

A failure means the capture ran and was evaluated, but the user did not pass. The SDK delivers it to your app as a failure result with three values: the failure type, a technical description, and the signed response from the server.

A failure is always the last result of a run. After it, no other result is sent for that run.

## Failure Types

Failures are decided by the liveness engine after the capture, not by the device. The failure type is the engine's most likely reason.

The types are the same on both platforms, spelled in each platform's naming style. See [Failure Reasons and User Guidance](https://docs.caf.io/sdk-lite/failure-handling/mobile/failure-handling.md#quick-reference) for every type in detail.

<table><thead><tr><th width="102.79296875">Group</th><th>What it means</th><th>Android</th><th>iOS</th></tr></thead><tbody><tr><td>Capture conditions</td><td>The light, the face position or the user's movement prevented a good capture.</td><td><code>MOTION_ISSUE</code>, <code>LIGHTING_ISSUES</code>, <code>FACE_NOT_FOUND</code>, <code>FRAMES_BLURRY</code>, <code>BACKGROUND_ISSUE</code></td><td><code>motionIssue</code>, <code>lightingIssues</code>, <code>faceNotFound</code>, <code>framesBlurry</code>, <code>backgroundIssue</code></td></tr><tr><td>Face</td><td>Something on or around the face blocked the check.</td><td><code>EYES_CLOSED</code>, <code>EYEWEAR</code>, <code>OBSCURED_FACE</code>, <code>MULTIPLE_FACES</code></td><td><code>eyesClosed</code>, <code>eyewear</code>, <code>obscuredFace</code>, <code>multipleFaces</code></td></tr><tr><td>Device</td><td>The device, or the way the app was built or installed, did not pass.</td><td><code>DEVICE_ISSUE</code>, <code>DEVICE_RESTART</code></td><td><code>deviceIssue</code>, <code>deviceRestart</code></td></tr><tr><td>Processing</td><td>The engine could not complete the evaluation. The cause is not the user.</td><td><code>UNKNOWN</code>, <code>SYSTEM_ERROR</code>, <code>REJECTED</code>, <code>TIMEOUT</code>, <code>PROCESSING_FAULT</code></td><td><code>unknown</code>, <code>systemError</code>, <code>rejected</code>, <code>timeout</code>, <code>processingFault</code></td></tr><tr><td>Registration</td><td>There is no biometric record of the user to compare against. Only in flows that compare the face with a registered one.</td><td><code>USER_NOT_FOUND</code></td><td><code>userNotFound</code></td></tr></tbody></table>

The enum also declares legacy types that the current versions no longer return, such as `TOO_DARK` and `FACE_TOO_FAR`. See [Legacy Types](https://docs.caf.io/sdk-lite/failure-handling/mobile/failure-handling.md#legacy-types) for the current equivalent of each one.

{% hint style="info" %}
When the run cannot start or cannot finish, the SDK returns an error instead, with no capture evaluated. See [Android Errors](https://docs.caf.io/sdk-lite/error-handling/android.md) and [iOS Errors](https://docs.caf.io/sdk-lite/error-handling/ios.md).
{% endhint %}

## What the SDK Does When a Failure Happens

* Delivers the failure with a **signed response** from the server, like a success.
* Registers the attempt with the Certta backend in the background, so it can be processed and queried later.
* Closes the capture screen and the loading screen, and stops the security monitoring.
* Ends the run, so a new capture can be started right away.

The configuration is kept, so you can start the SDK again without configuring it again.

## What Your App Should Do

1. **Send the signed response to your backend.** Validate it on your backend and use it as the source of truth. Never decide the outcome on the device.
2. **Guide the user.** Map the failure type to a localized message that tells the user what to do on the next attempt. Do not show the description or the type names to your users.
3. **Let the user try again when it can help.** Each failure type in [Failure Reasons and User Guidance](https://docs.caf.io/sdk-lite/failure-handling/mobile/failure-handling.md) says whether a new attempt helps.

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

```kotlin
CafFaceLivenessLite.instance.startLiveness { event ->
    if (event is LivenessLiteEvent.Failure) {
        sendToBackend(event.signedResponse)

        val message = when (event.type) {
            CafFailureType.LIGHTING_ISSUES -> getString(R.string.liveness_lighting)
            CafFailureType.FACE_NOT_FOUND -> getString(R.string.liveness_face_position)
            // ...
            else -> getString(R.string.liveness_try_again)
        }

        showRetryDialog(message)
    }
}
```

{% endtab %}

{% tab title="iOS" %}

```swift
extension YourViewController: CafFaceLivenessLiteDelegate {
    func didFinishWithFailure(type: CafFailureType, description: String?, signedResponse: String?) {
        sendToBackend(signedResponse)

        let message: String
        switch type {
        case .lightingIssues:
            message = NSLocalizedString("liveness_lighting", comment: "")
        case .faceNotFound:
            message = NSLocalizedString("liveness_face_position", comment: "")
        // ...
        default:
            message = NSLocalizedString("liveness_try_again", comment: "")
        }

        showRetryDialog(message)
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
`DEVICE_ISSUE` (`deviceIssue` on iOS) is also returned when the app does not pass the liveness engine’s injection checks, for example a debug build. On Android, with `enableSecurity = true` (the default), a debug build is blocked earlier by the Certta device checks and returns a `SECURITY_EXCEPTION` error instead. Before testing, see the security checks page for [Android](https://docs.caf.io/sdk-lite/setup/android/security-checks.md) and [iOS](https://docs.caf.io/sdk-lite/setup/ios/security-checks.md).
{% endhint %}

## Cancelled Is Not a Failure

When the user closes the capture screen or sends the app to the background during the capture, the SDK delivers a cancelled result. It is neither an error nor a failure: go back to the previous screen without showing an error message.

## Debugging

To investigate a failure, enable the SDK logs. Logs only appear when your app is debuggable, so the SDK never logs sensitive data such as the token or the signed response in production.

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

```kotlin
CafFaceLivenessLite.isLogEnabled = true
```

{% endtab %}
{% endtabs %}

## Next Steps

For every failure type in detail: [Failure Reasons and User Guidance](https://docs.caf.io/sdk-lite/failure-handling/mobile/failure-handling.md)

For how your backend handles the signed response that comes with a failure: [Backend Failures](https://docs.caf.io/sdk-lite/failure-handling/backend.md)


---

# 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/failure-handling/mobile.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.
