Error handling

The Keyless SDK uses three classes of errors, each error has an error code and an error message. Errors follow 3 main categories:

• Internal errors: triggered by Keyless internals.

• Integration errors: triggered by a KeylessSDK integration misconfiguration.

• User errors: triggered by unintended user behavior.

If you're implementing the Keyless SDK, you should handle errors coming from the SDK since the error message is not intended for end users.

Internal errors

Internal errors have code that are lower than 20_000. Internal errors require investigation from Keyless. If errors persist, please keep the error code, error message and stacktrace and contact us.

Integration errors

Integration errors have codes that span from 20_000 to 30_000. Integration errors can be solved by making sure you are not misusing the API surface of the SDK. You can solve it by reading the error message and addressing the issue. If errors persist, please keep the error code, error message and stacktrace and contact us.

User errors

Note that many of these errors are predictions only, when writing messages for your users it's often best to assume positive intent. For example, suggest that they make sure that nothing is obstructing the camera instead of suggesting that they are attempting to spoof.

User errors have code that are higher than 30_000. Intergration errors have code between 20_000 and 30_000.

Error	Code	Description
Spoofing	30000	The user might be placing a picture or a video in front of the camera.
Timeout	30001	The face could not be recognized before the specified timed out.
Mask detected	30002	The user might be wearing a mask, or there might be something hiding their face. Note: mask detected will be part of live feedback and no longer returned as an error from SDK version 4.8.0 and above.
User cancelled	30003	The user manually cancelled the face recognition and processing.
Face not matching	30004	The face of user in front of the camera does not match the face currently enrolled with Keyless.
No network connection	30005	The device appears to be offline.
Device tampered	30006	The device seems tampered and could have been rooted or jailbroken.
User lockout	30007	The user is temporarily locked out of Keyless after too many failed authentication attempts. In case of an enroll using the [temporary state](https://docs.keyless.io/consumer/mobile-sdk-guide/enrollment#temporary-state) the server could apply the lockout and in that case you would see an internal error with code `523`.
Rejected	30008	Keyless did not manage to recognize the user but does not suspect any spoofing attempt.
Camera denied	30009	The user denied camera permission.
Liveness Environment Aware	20021	The device does not meet the requirements for environment-aware liveness detection.

Examples

Android

val configuration = Keyless.AuthenticationConfiguration()

Keyless.authenticate(
    authenticationConfiguration = configuration,
    onCompletion = { result ->
        when (result) {
            is Keyless.KeylessResult.Success -> {
                Log.d("IntegratorActivity ", "Authenticate success")
            }
            is Keyless.KeylessResult.Failure -> {
                when (result.error) {
                    is KeylessUserError.FaceNotMatching -> Log.d("IntegratorActivity ", "Face not matching")
                    is KeylessUserError.MaskDetected -> Log.d("IntegratorActivity ", "Mask detected")
                    is KeylessUserError.Spoofing -> Log.d("IntegratorActivity ", "Spoofing detected")
                    is KeylessUserError.Timeout -> Log.d("IntegratorActivity ", "The operation timed out")
                    is KeylessUserError.UserCancelled -> Log.d("IntegratorActivity ", "The user cancelled the operation")
                    is KeylessUserError.NoNetworkConnection -> Log.d("IntegratorActivity ", "No network connection available")
                    is KeylessUserError.Lockout -> Log.d("IntegratorActivity ", "Your account is temporarily locked")
                    else -> {
                        Log.d("IntegratorActivity ", "Authenticate failure")

                        val errorCode = result.error.code
                        val errorMessage = result.error.message
                        val errorCause = result.error.cause?.printStackTrace()
                        // here you could display a generic error popup with the error code
                    }
                }
            }
        }
    }
)

iOS

let configuration = Keyless.AuthenticationConfiguration.builder.build()

Keyless.authenticate(authenticationConfiguration: configuration) { result in
    switch result {
    case .success(let authenticationSuccess):
        print("authenticationDidFinish:  \(authenticationSuccess.token)")
    case .failure(let error):
        switch error.kind {
        case .userError(let userError):
            switch userError {
            case .faceNotMatching:
                print("Face not matching")
            case .maskDetected:
                print("Mask detected")
            case .spoofing:
                print("Spoofing detected")
            case .timeout:
                print("The operation timed out")
            case .userCancelled:
                print("The user cancelled the operation")
            case .noNetworkConnection:
                print("No network connection available")
            case .lockout:
                print("Your account is temporarily locked")
            }
        default:
            let code = error.code
            let message = error.message
            // here you could display a generic error popup with the error code
        }
    }
}

Flutter

import 'package:keyless_flutter_sdk/keyless.dart';
import 'package:keyless_flutter_sdk/models/configurations/authentication_configuration.dart';

final configuration = BiomAuthConfig();

try {
  final result = await Keyless.instance.authenticate(configuration);
  print("Authentication successful");
} catch (error) {
  if (error is KeylessError) {
    switch (error.errorType) {
      case KeylessErrorType.user:
        if (error.code == KeylessErrorCase.faceNotMatching.code) {
          print("Face not matching");
        } else if (error.code == KeylessErrorCase.maskDetected.code) {
          print("Mask detected");
        } else if (error.code == KeylessErrorCase.spoofing.code) {
          print("Spoofing detected");
        } else if (error.code == KeylessErrorCase.timeout.code) {
          print("The operation timed out");
        } else if (error.code == KeylessErrorCase.userCancelled.code) {
          print("The user cancelled the operation");
        } else if (error.code == KeylessErrorCase.noNetworkConnection.code) {
          print("No network connection available");
        } else if (error.code == KeylessErrorCase.deviceTampered.code) {
          print("Device security check failed");
        } else if (error.code == KeylessErrorCase.lockout.code) {
          print("Your account is temporarily locked");
        }
        break;
      default:
        // Handle internal or integration errors
        print("Authentication failed: ${error.message} (Code: ${error.code})");
        // Here you could display a generic error popup with the error code
    }
  }
}