Error Handling
The PingOne Recognize SDK uses three classes of errors. Each error has an error code and an error message:
-
User errors: triggered by unintended or suspicious user behavior (
30_000and above). -
Integration errors: triggered by a PingOne Recognize SDK integration misconfiguration (
20_000to30_000). -
Internal errors: triggered by PingOne Recognize internals (below
20_000).
If you are implementing the PingOne Recognize SDK, handle errors coming from the SDK because the raw error message is not intended for end users.
User Errors
User errors have codes 30_000 and above.
|
Many of these errors are predictions only. When writing messages for users, it is often best to assume positive intent. For example, suggest checking whether anything is obstructing the camera instead of suggesting spoofing. |
| Error | Code | Description | Recommendations |
|---|---|---|---|
Spoofing |
|
The user’s genuine presence cannot be established. |
The user might be placing a picture or a video in front of the camera. Our system is probabilistic, upon failure, advise users to ensure their face is well-lit and fully visible before retrying. The user can utilize live feedback during the camera scan for real-time guidance. |
Timeout |
|
The face could not be recognized before the specified timed out. Note: This error is no longer returned from SDK version |
The user can retry placing the face in front of the camera as soon as the camera opens. |
Mask detected |
|
The user might be wearing a mask, or something might be hiding their face. Note: Mask detected is part of live feedback and is no longer returned as an error from SDK version 4.8.0 and above. |
It is very likely that there is some occlusion on the face. We advise to retry and utilize the live feedback during the camera scan for real-time guidance. |
User cancelled |
|
The user manually cancelled face recognition or image processing. |
This error occurs when the user cancels the face scan with the back button. We recommend either suppressing the error (the event is logged internally for debugging) or prompting the user to retry in case the cancellation was accidental. |
Face not matching |
|
The face of the user in front of the camera doesn’t match the face currently enrolled with PingOne Recognize. |
This indicates a biometric mismatch: a face was detected, but it does not match the enrolled profile. We recommend prompting a retry or advising the user to verify they have selected the correct account. |
No network connection |
|
The device appears to be offline. |
This error indicates a loss of network connectivity. We recommend prompting the user to verify their internet connection and restart the scan. If the issue persists, advise them to wait a few minutes before retrying. |
Device tampered |
|
The device seems tampered and could have been rooted or jailbroken. Note: This error has been superseded by runtime application self protection. |
This error suggests that the device is likely rooted or jailbroken. Advise the user to try on another device. If not possible reach out to Keyless support for further guidance. |
User lockout |
|
The user is temporarily locked out of PingOne Recognize after too many failed authentication attempts.
Note: For new device activation, a different lockout code |
We advise the user to wait for the indicated time. We advise to expose to the user a functionality to check the remaining time from the app before retrying. The customer can use the APIs in the Lockout management section. |
Rejected |
|
PingOne Recognize did not manage to recognize the user but does not suspect any spoofing attempt. |
The model is not providing further hints on the issue. We advise users to utilize the live feedback during the camera scan for real-time guidance. |
Camera denied |
|
The user denied camera permission. |
We advise the customer app to ensure camera permissions are granted. If needed, prepare an informative screen on why the camera permissions are necessary to perform the face scan. |
Integration Errors
Integration errors have codes from 20_000 to 30_000.
Integration errors can be solved by ensuring the SDK API surface is used correctly. If errors persist, keep the error code, message, and stack trace, then contact support.
| Error | Code | Description | Recommendations |
|---|---|---|---|
User Not Enrolled |
|
The user is not enrolled and you are likely trying to authenticate the user. It is necessary to enroll the user first. |
We advise to verify that the user is not enrolled before calling |
User Already Enrolled |
|
You are likely trying to enroll the user, but there is an already enrolled user on the device. |
If you need to enroll a new user call |
Legacy SDK configure failed |
|
This error should no longer be returned and has been replaced by the error |
Refer to |
SDK configure failed |
|
There was an error when calling Keyless.configure. Note: From SDK version 6.0.0 and above, the configuration error will be more fine grained. Check the error message to understand the actual issue. |
This error typically occurs due to misconfigured tenant feature flags or a failure to reach the feature flag service during SDK setup. In rare cases, it may also be caused by insufficient device storage preventing the SDK from writing necessary local files. |
Liveness Environment Aware |
|
The device does not meet the requirements for environment-aware liveness detection. Note: From SDK version 6.0.0 and above, the liveness environment aware check will be managed internally in the SDK. |
We advise the customer to turn-off the liveness environment aware feature if this creates frictions for the users. |
Internal Errors
All errors below 20_000 are internal errors and relate to responses from the core platform. These typically require PingOne Recognize support investigation, though some can be actioned by integrators.
| Error | Code | Description | Recommendation |
|---|---|---|---|
|
|
Client-server mismatch suggesting an issue communicating with the Core backend. |
This could be due to network drop, or an outdated (unsupported) core client trying to contact the latest core backend. |
|
|
The given user selfie did not meet the threshold of an approved match. In simple terms, confidence was not high enough that this was the same face registered to this PingOne Recognize ID. |
In most cases, advise positive intent and ask the user to retry in a well-lit environment, with face centered and nothing covering the face. Integrators should also consider that this can occur when the person attempting authentication is not the registered person. |
|
|
The core backend and core client cannot agree on the selected circuit. This can be caused by the local storage synchronization failures. |
We advise to retry the authentication, if enough circuits are available sync should be fixed with further authentications. If the issue persists, we advise to enroll the user anew. |
|
|
Core backend returned a 400 HTTP status error. |
We advise to retry the operation. If the issue persists prompt the user to wait a few minutes before retrying. Lastly, if the user still sees the same error we advise to enroll the user anew. |
|
|
The maximum number of devices has been reached. Maximum is 50 devices per PingOne Recognize ID. These may include backup or temporary client states, not only physical devices. |
Revoke existing states/devices to generate new ones. For SaaS customers, this can be done in PingOne Recognize dashboard or through the Server API . |
|
|
Network unavailable or server response unexpected. |
If networking is available, refer to |
|
|
Incorrect or invalid parameter passed to a core function. |
This may be solved by re-running the PingOne Recognize enrollment or authentication request. Alternatively, SDK/core client sync may be corrupted. |
|
|
The local state of the Keyless SDK - core client - might not be in sync with the core backend. |
This may happen also in case the device time is not set correctly. We advise to ensure the device is genuine and has a correct time setting, If the issue persists, we advise to enroll the user anew. |
|
|
It is possible that you are trying to authenticate the user with the PIN but the PIN was never set for that user. |
We advise to ensure that the pin authentication factor is enabled and has been set for the user. |
|
|
Legacy: should be re-mapped to |
Refer to |
|
|
It is not possible to configure the KeylessLogsConfiguration. Learn more in logging. |
We advise to make sure there was no connectivity drop during the setup and retry again to call Keyless.configure. |
If errors in this range persist and are unclear, keep the error code, error message, and stack trace and contact support. If possible, enable PingOne Recognize logging at TRACE level and share those logs to speed investigation.
Anti-Inject Errors
The following errors apply to PingOne Recognize Anti-Inject variant only.
| Error | Code | Description |
|---|---|---|
Anti-inject initialization failed |
|
(PingOne Recognize Anti-Inject variant only.) Initialization of Anti-Inject failed for an internal error. |
License expired |
|
(PingOne Recognize Anti-Inject variant only.) The license |
Device might not be genuine |
|
(PingOne Recognize Anti-Inject variant only.) Signals indicate this device may be compromised or not genuine. This prevents the user from continuing and enrollment/authentication is not possible. |
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()
// 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
// 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:
print("Authentication failed: ${error.message} (Code: ${error.code})");
}
}
}