# SDK error codes
# Client errors
The table below lists all errors that are triggered from the Encap SCA SDK. We refer to these as client errors.
| Code | Error name | Applicable platforms | Description (in English) |
| 100 | clientErrorOperationInProgress | Android, iOS | Another operation is in progress. Wait for it to finish before issuing new requests. |
| 101 | clientErrorConnectionFailure | Android, iOS | The server could not be reached. The network may be down, there may be firewall issues, or the server may be suffering high loads. Exemption in the iOS localisation key, for this error it is client.error.connection |
| 102 | clientErrorInvalidResponse | Android, iOS | The server response could not be understood by the Encap API. Example: This may occur because of an internal server error, or a malconfigured reverse proxy. |
| 102 | clientErrorInvalidResponse | Android, iOS | The server response could not be understood by the Encap API. Example: This may occur because of an internal server error, or a malconfigured reverse proxy. |
| 105 | clientErrorInvalidInputFormat | Android, iOS | The given input does not comply with the policy proposed by the Encap server. |
| 106 | clientErrorNotActivated | Android, iOS | The client has not yet been activated or was deactivated. Hence, it was not preceded by a successful activate call. |
| 109 | clientErrorUnexpected | Android, iOS | An unexpected error occurred on the client. |
| 110 | clientErrorWrongState | Android, iOS | The attempted operation is not allowed in this state. Example: The corresponding start operation needs to be performed before the finish operation. |
| 111 | clientErrorConfiguration | Android, iOS | Configuration error. The attempted operation is not possible to perform with the current configuration. Example: The public key used for end-to-end encryption is not configured correctly. |
| 120 | clientErrorConnectionTimeout | Android, iOS | The request to the Encap server timed out. |
| 121 | clientErrorNoInternetConnection | Android, iOS | No internet connection. |
| 122 | clientErrorSecureConnectionCheckFailed | Android, iOS | The secure connection check performed by the client failed. |
| 127 | clientErrorInvalidAuthParameters | iOS | Invalid authentication parameters provided. |
| 128 | clientErrorAuthMethodUnavailable | Android, iOS | The authentication method is not supported or active. Example: Touch ID has been disabled. |
| 129 | clientErrorAuthMethodNotAllowed | Android, iOS | The authentication method is not activated or not supported for this operation |
| 130 | clientErrorAuthenticationFailed | iOS | Biometric authentication on the device has failed. |
| 131 | clientErrorAuthenticationAborted | iOS | Biometric authentication on device was aborted. |
| 132 | clientErrorAuthDataInvalidated | Android, iOS | The authentication data was invalidated. Biometrics have been added or removed. |
| 133 | clientErrorDowngradeDetected | Android, iOS | The API is downgraded, which is not supported. Deactivate locally, or reinstall the app to resolve the issue. |
| 134 | EncapClientErrorRegistrationDataInvalidated | iOS | A local deactivation has been performed, since registration data is missing due to a backup/restore. |
| 135 | clientErrorRegistrationDataTooOld | Android, iOS | Registration data stored on the device has been created with an outdated version of the Encap protocol. It is not possible to perform an authentication without reactivation. |
| 140 | clientErrorOfflineVersionNotSupported | Android, iOS | The provided verificationData is not supported by this version of the EncapAPI. The client needs to be updated. |
| 141 | clientErrorOfflineParsingFailed | Android, iOS | Parsing of the verificationData failed. At least one of the fields is missing or invalid. |
| 150 | clientErrorTokenPurposeNotSupported | Android, iOS | The purpose for obtaining a token is not supported. |
| 151 | clientErrorInvalidToken | Android, iOS | The provided Encap token is not valid, or it is expired. |
| 152 | clientErrorInvalidRecoveryParameters | Android, iOS | One of the provided recovery parameters is not valid. |
| 153 | clientErrorRecoveryDataNotPresent | Android, iOS | Recovery data is not present in the backup. This could be due to problems with backup/restore, or a lack of recovery being added. |
| 160 | clientErrorAppAttestNotSupportedInExtension | iOS | App attestation is not supported from the extension in required mode. An authentication is required to be able to use this operation. |
| 161 | clientErrorOperationNotAllowedInExtension | iOS | The current operation is not allowed from an extension. |
| 170 | clientErrorCrypto | Android | An internal crypto error occurred in the client. This could occur if the required crypto functionality is not available on the device. |
| 171 | clientErrorIntegrity | Android | The integrity check of the client data failed. This might happen if the data has been tampered with. |
| 172 | clientErrorStorage | Android, iOS | An error occurred while reading/writing client data. This could happen if the device is short on storage capacity. |
| 174 | clientErrorStorageUnavailable | iOS | Storage is unavailable. Failed to read or write data. Example: This could occur if the device is locked. |
| 175 | clientErrorStorageNeedSharedGroup | iOS | Storage is unavailable. Failed to read or write data. This happened because extension support is enabled, but the App Group is not available. |
| 181 | clientErrorKeyUserNotAuthenticated | Android | The end-user was not authenticated with a biometric strong enough to be used with the Android KeyStore. The end-user can try to recover by changing the preferred biometric in the settings on the device, if possible. |
| 182 | clientErrorBiometricAuthentication | Android | General error code for biometric authentication. This error indicates that there is a low-level encryption/decryption error of the data, involving the cipher and key protected by the biometrics, for example caused by javax.crypto.IllegalBlockSizeException or javax.crypto.BadPaddingException.The data to be encrypted/decrypted in this case is a random number named biometric salt, stored on file (shared preferences), used in the authentication algorithm. |
| 183 | clientErrorUniqueDeviceIdInvalidAlgorithm | Android | The algorithm for getting the unique device identifier is unsupported. |
| 184 | clientErrorUniqueDeviceIdAccessFailure | Android | A problem occurred when getting the unique device identifier. |
| 1101 | clientErrorAndroidFingerprintAuthenticationFailed | Android | A fingerprint is valid, but not recognised. Example: This error may occur if the end-user pushes a non-registered finger on the fingerprint sensor. Typically for this error code, an app will display information to the end-user that the finger was not recognised. |
| 1102 | clientErrorAndroidFingerprintAcquiredImagerDirty | Android | The fingerprint image was too noisy due to suspected or detected dirt on the sensor. |
| 1103 | clientErrorAndroidFingerprintAcquiredInsufficient | Android | The fingerprint image was too noisy to process due to a detected condition (i.e. dry skin), or a possibly dirty sensor. |
| 1104 | clientErrorAndroidFingerprintAcquiredPartial | Android | Only a partial fingerprint image was detected. |
| 1105 | clientErrorAndroidFingerprintAcquiredTooFast | Android | The fingerprint image was incomplete due to quick motion. |
| 1106 | clientErrorAndroidFingerprintAcquiredTooSlow | Android | The fingerprint image was unreadable due to lack of motion. |
| 1107 | clientErrorAndroidFingerprintUnexpectedHelpcode | Android | The Android Fingerprint API returned an unexpected help code. |
| 1108 | clientErrorAndroidFingerprintErrorCanceled | Android | The operation was cancelled because the fingerprint sensor is unavailable. Example: This may happen when the end-user is switched, the device is locked, or another pending operation prevents or disables it. |
| 1109 | clientErrorAndroidFingerprintErrorHwUnavailable | Android | The hardware is unavailable. Try again later. |
| 1110 | clientErrorAndroidFingerprintErrorLockout | Android | The operation was cancelled because the API is locked out due to too many attempts. |
| 1111 | clientErrorAndroidFingerprintErrorNoSpace | Android | The error state returned for operations like enrolment. The operation cannot be completed because there is not enough storage remaining to complete the operation. |
| 1112 | clientErrorAndroidFingerprintErrorTimeout | Android | The error state returned when the current request has been running too long. This is intended to prevent programs from waiting for the fingerprint sensor indefinitely. The timeout is platform and sensor-specific, but it is generally around 30 seconds. |
| 1113 | clientErrorAndroidFingerprintErrorUnableToProcess | Android | The error state returned when the sensor was unable to process the current image. |
| 1114 | clientErrorAndroidFingerprintErrorUnexpectedErrorCode | Android | The Android Fingerprint API returned an unexpected help code. |
| 1115 | clientErrorAndroidFingerprintErrorVendorSpecific | Android | A vendor-specific error that does not fit any of the other categories. The UI is expected to show the error string. |
| 1116 | clientErrorAndroidFingerprintErrorLockoutPermanent | Android | You get this when the error clientErrorAndroidFingerprintErrorLockout happens too many times. |
| 1117 | clientErrorAndroidFingerprintErrorUserCanceled | Android | The operation was cancelled because the end-user cancelled the operation. |
| 1118 | clientErrorAndroidFingerprintErrorNoFingerprints | Android | The end-user does not have any fingerprints enrolled. |
| 1119 | clientErrorAndroidFingerprintHwNotPresent | Android | The device does not have a fingerprint sensor. |
| 1200 | clientErrorAndroidBiometricPromptAuthenticationFailed | Android | A biometric is valid but not recognised. Example: This error may occur if the end-user pushes a non-registered finger on the fingerprint sensor. Normally, no action is needed from the app for this error code, as the BiometricPrompt will handle the UI and let the end-user retry. |
| 1201 | clientErrorAndroidBiometricPromptAcquiredGood | Android | The image acquired was good. |
| 1202 | clientErrorAndroidBiometricPromptAcquiredPartial | Android | Only a partial biometric image was detected. During enrolment, the end-user should be informed on what needs to happen to resolve this problem. Example: For fingerprint, "Press firmly on the sensor.". |
| 1203 | clientErrorAndroidBiometricPromptAcquiredInsufficient | Android | The biometric image was too noisy to process due to a detected condition or a possibly dirty sensor. |
| 1204 | clientErrorAndroidBiometricPromptAcquiredImagerDirty | Android | The biometric image was too noisy due to suspected or detected dirt on the sensor. Example: It is reasonable to return this after multiple {clientErrorAndroidBiometricPromptAcquiredInsufficient} or actual detection of dirt on the sensor (stuck pixels, swaths, etc.). The end-user is expected to take action to clean the sensor when this is returned. |
| 1205 | clientErrorAndroidBiometricPromptAcquiredTooSlow | Android | The biometric image was unreadable due to lack of motion. |
| 1206 | clientErrorAndroidBiometricPromptAcquiredTooFast | Android | The biometric image was incomplete due to quick motion. Example: This could happen if the end-user moved during acquisition. The end-user should be asked to repeat the operation more slowly. |
| 1207 | clientErrorAndroidBiometricPromptUnexpectedHelpCode | Android | The Android BiometricPrompt API returned an unexpected help code. |
| 1211 | clientErrorAndroidBiometricPromptErrorHwUnavailable | Android | The hardware is unavailable. Try again later. |
| 1212 | clientErrorAndroidBiometricPromptErrorUnableToProcess | Android | The error state returned when the sensor was unable to process the current image. |
| 1213 | clientErrorAndroidBiometricPromptErrorTimeout | Android | The error state returned when the current request has been running too long. This is intended to prevent programs from waiting for the biometric sensor indefinitely. The timeout is platform and sensor-specific, but is generally around 30 seconds. |
| 1214 | clientErrorAndroidBiometricPromptErrorNoSpace | Android | The error state returned for operations like enrolment. The operation cannot be completed because there is not enough storage remaining to complete the operation. |
| 1215 | clientErrorAndroidBiometricPromptErrorCanceled | Android | The operation was cancelled because the biometric sensor is unavailable. Example: This may happen when the end-user is switched, the device is locked or another pending operation prevents or disables it. |
| 1217 | clientErrorAndroidBiometricPromptErrorLockout | Android | The operation was cancelled because the API is locked out due to too many attempts. This occurs after 5 failed attempts, and lasts for 30 seconds. |
| 1218 | clientErrorAndroidBiometricPromptErrorVendor | Android | Hardware vendors may extend this list if there are conditions that do not fall under one of the above categories. Vendors are responsible for providing error strings for these errors. These messages are typically reserved for internal operations such as enrolment, but may be used to express vendor errors not otherwise covered. Applications are expected to show the error message string if they happen, but are advised not to rely on the message ID since they will be device and vendor-specific. |
| 1219 | clientErrorAndroidBiometricPromptErrorLockoutPermanent | Android | The operation was cancelled because BIOMETRIC_ERROR_LOCKOUT occurred too many times. Biometric authentication is disabled until the end-user unlocks with strong authentication (PIN/Pattern/Password). |
| 1220 | clientErrorAndroidBiometricPromptErrorUserCanceled | Android | The end-user cancelled the operation. Upon receiving this, applications should use an alternate authentication such as a password. The application should also provide the means to return to biometric authentication, such as with a "Use Biometric" button. |
| 1221 | clientErrorAndroidBiometricPromptErrorNoBiometrics | Android | The end-user does not have any biometrics enrolled. |
| 1222 | clientErrorAndroidBiometricPromptErrorHwNotPresent | Android | The device does not have a biometric sensor. |
| 1223 | clientErrorAndroidBiometricPromptErrorNegativeButton | Android | The end-user pressed the negative button. This is a placeholder that is currently only used by the support library. |
| 1224 | clientErrorAndroidBiometricPromptErrorNoDeviceCredential | Android | The device does not have a PIN code, pattern, or password set up. |
| 1225 | clientErrorAndroidBiometricPromptErrorSecurityUpdateRequired | Android | A security vulnerability has been discovered. The sensor is unavailable until a security update has addressed this issue. |
| 1233 | clientErrorAndroidBiometricPromptErrorUnexpectedErrorCode | Android | The Android BiometricPrompt API returned an unexpected error code. |
# Server errors
In the table below you can find all errors that are triggered from the Encap SCA server, we refer to them as server errors.
| Code | Error name | Applicable platforms | Description (in English) |
| 200 | serverErrorActivationCodeVerification | Android, iOS | The server was not able to look up an activation session from the given activation code. |
| 201 | serverErrorUnexpected | Android, iOS | An unexpected problem occurred at the server. |
| 202 | serverErrorNotRegistered | Android, iOS | The registration is not yet known to the server (any more). The registration ID may be incorrect or the registration may have been deleted from the server. |
| 203 | Mapped to serverErrorUnexpected | iOS | The registration is not yet fully activated as it has not been preceded by a successful activate call. |
| 204 | Mapped to serverErrorUnexpected | iOS | The operation requires an authenticated session, but the session is not yet fully authenticated as it has not been preceded by a successful authenticate call. |
| 205 | Mapped to serverErrorUnexpected | iOS | The operation has not been initiated yet. The register/identify call is missing. |
| 206 | Mapped to serverErrorUnexpected | iOS | The registration has already been activated. There is an activate call after a successful activate call. |
| 207 | serverErrorAlreadyAuthenticated | Android, iOS | The session has already been authenticated. There is a call that does not require authentication after a successful authentication call. |
| 208 | serverErrorNoSession | Android, iOS | There is no active session found for the request. |
| 209 | serverErrorExpiredSession | Android, iOS | The active session has expired and cannot be used any more. A new session must be created by the end-user (service provider). |
| 210 | serverErrorInvalidSession | Android, iOS | An operation was attempted on a session that is in an invalid state. Please do another start authenticate before retrying finish authenticate. |
| 211 | serverErrorClientOnlyDisallowed | Android, iOS | The server is configured to disallow client-initiated sessions. This is a configuration error that should not occur during normal operation. |
| 213 | serverErrorIncorrectResponse | Android, iOS | Activation failed on the server because the verification of the client response to the server activation challenge failed, or verification of hardware key signature. |
| 214 | serverErrorAuthenticationFailed | Android, iOS | Incorrect response to authentication challenge. Example: Wrong PIN code, authentication failed. |
| 219 | serverErrorApplicationIdMismatch | Android, iOS | The application ID sent by the client did not match the application ID expected by the server. |
| 221 | serverErrorServiceUnavailable | Android, iOS | The server could not be reached or is having technical difficulties. |
| 224 | serverErrorLockedByAdmin | Android, iOS | The registration was locked down by the server for a reason. Example: Locked by admin or customer support. |
| 226 | serverErrorLocked | Android, iOS | The registration is locked because the maximum number of authentication attempts was exceeded or device verification failed. |
| 230 | serverErrorNoMatchingAuthMethod | Android, iOS | Could not find an authentication method with the same or higher level as requested by the Encap server. |
| 231 | serverErrorIllegalAuthMethod | Android, iOS | The client tried to activate with an authentication method not allowed by the server's configuration. Example: Activate fingerprint when the server allows DEVICE and DEVICE:PIN. |
| 232 | serverErrorIllegalAuthFactor | Android, iOS | Trying to use single-factor authentication when two-factor authentication is required. |
| 233 | serverErrorAuthenticationRequired | Android, iOS | An authentication is required to be able to use this operation, to upgrade to a new protocol. |
| 235 | serverErrorAuthMethodNotAllowed | Android, iOS | The specified authentication method is not allowed for this session. |
| 236 | serverErrorNoSessionForPurpose | Android, iOS | A session exists with another purpose set than in the request from the client. The current authentication session might have been replaced with a new session. |
| 237 | serverErrorApplicationIdNotFound | Android, iOS | The application ID does not exist. |
| 238 | serverErrorApiVersionTooOldForServer | Android, iOS | The API version is too old for the server. |
| 239 | serverErrorApiVersionTooNewForServer | Android, iOS | The API version precedes the server. |
| 240 | serverErrorApiVersionTooOldForAppConfig | Android, iOS | The application configuration has specified the version as outdated. |
| 241 | serverErrorApiVersionBlacklisted | Android, iOS | The application configuration has explicitly blocklisted (sometimes referred to as blacklisted) this version. |
| 242 | serverErrorEncapServerToServiceProviderError | Android, iOS | Something has gone wrong with the communication between the server and the service provider. |
| 243 | serverErrorNotParsable | Android, iOS | The internal request parameter is not parsable. |
| 244 | serverErrorMissingParameter | Android, iOS | The internal request is missing a required input parameter. |
| 245 | serverErrorMalformedParameter | Android, iOS | The internal request parameter is malformed. |
| 246 | serverErrorActivationFailed | Android, iOS | The start activation failed, but the client tried to finish the activation anyway. |
| 249 | serverErrorClientRequestTimeOutOfSync | Android, iOS | The request has an older timestamp than the previous request. Either the request was delayed on the way, or the clock on the phone has been set back in time. The end-user needs to wait CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD ms and try again.See the server manual for details. |
| 250 | serverErrorReactivationOnUnknownDevice | Android, iOS | Reactivation must be performed on the same device as it was activated on. |
| 254 | serverErrorAuthTokenCreationFailed | Android, iOS | Creation of the authentication token failed server-side. |
| 255 | serverErrorAuthTokenValidationFailed | Android, iOS | Validation of the authentication token failed server-side. |
| 256 | serverErrorAuthTokenAlreadyUsed | Android, iOS | The provided token has already been used during another operation and cannot be used again. |
| 257 | serverErrorRecoveryAlreadyUsed | Android, iOS | Recovery has already been used. Each recovery can be used only once. |
| 258 | serverErrorRecoveryDoesNotExist | Android, iOS | Recovery secrets are missing or have never been created for a selected account. |
| 259 | serverErrorRecoveryDisabled | Android, iOS | Recovery operations have been disabled for either the given registration or selected application configuration. |
| 260 | serverErrorRecoveryLocked | Android, iOS | Recovery has been locked and cannot be used. |
| 261 | serverErrorInvalidAuthTokenPurpose | Android, iOS | Token with the wrong purpose has been used to perform an operation. |
| 262 | serverErrorInvalidAuthLevelForTokenRequest | Android, iOS | Token request requires two-factor authentication. |
| 270 | serverErrorGeofencingBoundaryValidationFailed | Android, iOS | Server evaluation of the country against allowed regions failed. |
| 271 | serverErrorGeofencingClientFailure | Android, iOS | The client failed to obtain a location or the geocode lookup failed. |
| 280 | serverErrorAppAttestUnexpectedError | iOS | An unexpected failure occurred while processing AppAttest data. Check the error message for more details. |
| 281 | serverErrorAppAttestTimeout | iOS | Timeout while performing App Attest operation. |
| 282 | serverErrorAppAttestNotSupported | iOS | The device does not support App Attest. |
| 283 | serverErrorAppAttestServerUnavailable | iOS | The Apple App Attest server is unavailable. |
| 285 | serverErrorInvalidPublicKeyForApplicationId | Android, iOS | No key pair for public key. |
| 286 | serverErrorPlayIntegrityTimeout | Android | The activation or authentication failed due to the client timing out when performing Play Integrity Attestation. |
| 287 | serverErrorPlayIntegrityApiFailure | Android | The activation or authentication failed due to the client encountering an API failure when performing Play Integrity Attestation. |
| 288 | serverErrorPlayIntegrityPlayServicesOutOfDate | Android | The activation or authentication failed due to the client being unable to use Google Play when performing Play Integrity Attestation. |
# Recoverable errors
isRecoverableError indicate if the error is recoverable or final in a finish operation. It will return true if the error is recoverable, otherwise false.
See the tables below for which errors that are recoverable on the different platforms.
Android
| Code | Error name |
| 105 | clientErrorInvalidInputFormat |
| 214 | serverErrorAuthenticationFailed |
| 1101 | clientErrorAndroidFingerprintAuthenticationFailed |
| 1102 | clientErrorAndroidFingerprintAcquiredImagerDirty |
| 1103 | clientErrorAndroidFingerprintAcquiredInsufficient |
| 1104 | clientErrorAndroidFingerprintAcquiredPartial |
| 1105 | clientErrorAndroidFingerprintAcquiredTooFast |
| 1106 | clientErrorAndroidFingerprintAcquiredTooSlow |
| 1107 | clientErrorAndroidFingerprintUnexpectedHelpcode |
| 1200 | clientErrorAndroidBiometricPromptAuthenticationFailed |
| 1202 | clientErrorAndroidBiometricPromptAcquiredPartial |
| 1203 | clientErrorAndroidBiometricPromptAcquiredInsufficient |
| 1204 | clientErrorAndroidBiometricPromptAcquiredImagerDirty |
| 1205 | clientErrorAndroidBiometricPromptAcquiredTooSlow |
| 1206 | clientErrorAndroidBiometricPromptAcquiredTooFast |
| 1207 | clientErrorAndroidBiometricPromptUnexpectedHelpCode |
iOS
| Code | Error name |
| 100 | clientErrorOperationInProgress |
| 105 | clientErrorInvalidInputFormat |
| 120 | clientErrorConnectionTimeout |
| 121 | clientErrorNoInternetConnection |
| 130 | clientErrorAuthenticationFailed |
# iOS localisation key
For all iOS errors, there is a localisation key. The localisation key is the error name prefixed with client.error. or server.error..