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
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. This could be due to either: The network being be down. Firewall issues. The server undergoing high loads. Note: There is an 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 could be caused by internal server error, or a misconfigured 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. This means that the operation 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	There is a configuration error. This means that the attempted operation is not possible to perform with the current configuration. Example: This could be caused by an incorrectly configured public key used for end-to-end encryption.
120	clientErrorConnectionTimeout	Android, iOS	The request to the Encap server timed out.
121	clientErrorNoInternetConnection	Android, iOS	There is no internet connection.
122	clientErrorSecureConnectionCheckFailed	Android, iOS	The secure connection check performed by the client failed.
127	clientErrorInvalidAuthParameters	iOS	The authentication parameters that were provided are invalid.
128	clientErrorAuthMethodUnavailable	Android, iOS	The authentication method is not supported or active. Example: This could be caused by Touch ID being 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 cancelled.
132	clientErrorAuthDataInvalidated	Android, iOS	The authentication data was invalidated. Biometrics have been added or removed.
133	clientErrorDowngradeDetected	Android, iOS	The API is not supported because it has been downgraded. Note: To resolve the issue, you must either: Deactivate locally. Reinstall the app.
134	EncapClientErrorRegistrationDataInvalidated	iOS	The registration data is missing due to a backup or restore. This means that a local deactivation has been performed.
135	clientErrorRegistrationDataTooOld	Android, iOS	The registration data stored on the device was created with an outdated version of the Encap protocol. This means that the client SDK version is new enough, but the device has not communicated with the Encap server in a significant amount time (three years before the introduction of the server version). Note: It is not possible to perform an authentication without reactivation.
136	clientErrorUnauthorized	Android, iOS	The server could not find a key pair matching the provided public key hash. You must ensure that the public key is correctly configured.
140	clientErrorOfflineVersionNotSupported	Android, iOS	The provided verificationData is not supported by this version of the Encap API. This means that the client needs to be updated.
141	clientErrorOfflineParsingFailed	Android, iOS	The verificationData failed to be parsed, as 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 has 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 because: There are problems with backup/restore. Recovery has not been 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. Example: This could be caused by data that has been tampered with.
172	clientErrorStorage	Android, iOS	An error occurred whilst reading/writing client data. Example: This could be caused by limited storage capacity on the device.
174	clientErrorStorageUnavailable	iOS	Storage is unavailable. Failed to read or write data. Example: This could be caused by the device being locked.
175	clientErrorStorageNeedSharedGroup	iOS	Storage is unavailable. Failed to read or write data. Note: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 method strong enough to be used with the Android KeyStore. If possible, the end-user can attempt to recover by changing the preferred biometric method in the settings on the device.
182	clientErrorBiometricAuthentication	Android	A 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. Example: This could be caused by javax.crypto.IllegalBlockSizeException or javax.crypto.BadPaddingException. In this case, the data to be encrypted/decrypted is a random number named biometric salt. This is stored on file in shared preferences, and 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.
1200	clientErrorAndroidBiometricPromptAuthenticationFailed	Android	A biometric method 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 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 with 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 error after multiple {clientErrorAndroidBiometricPromptAcquiredInsufficient}, or after detection of dirt on the fingerprint sensor (across a single or multiple pixels). 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 sensor was unable to process the current image.
1213	clientErrorAndroidBiometricPromptErrorTimeout	Android	The current request has been running too long. Note: This is intended to prevent programs from waiting for the biometric sensor indefinitely. The timeout is platform and sensor-specific, but is generally approximately 30 seconds.
1214	clientErrorAndroidBiometricPromptErrorNoSpace	Android	The operation cannot be completed because there is not enough storage remaining to complete the operation. Note: This error state is returned for operations such as enrolment.
1215	clientErrorAndroidBiometricPromptErrorCanceled	Android	The operation was cancelled because the biometric sensor is unavailable. Example: This could be caused by: The end-user being switched. The device being locked. Another pending operation preventing or disabling 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 such as: PIN code. 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. Note: 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

The table below lists all errors that are triggered from the Encap SCA server. We refer to these as server errors.

Code	Error name	Applicable platforms	Description
200	serverErrorActivationCodeVerification	Android, iOS	The server was unable to look up an activation session from the given activation code.
201	serverErrorUnexpected	Android, iOS	An unexpected problem occurred on the server.
202	serverErrorNotRegistered	Android, iOS	The registration ID (registrationId) cannot be found.
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 yet been initiated. The register/identify call is missing.
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. You must undertake another start authentication operation before retrying the finish authentication operation.
211	serverErrorClientOnlyDisallowed	Android, iOS	The server is configured to disallow client-initiated sessions. Note: This is a configuration error that should not occur during normal operation.
213	serverErrorIncorrectResponse	Android, iOS	Activation failed on the server because either: The verification of the client response to the server activation challenge failed. Verification of hardware key signature failed.
214	serverErrorAuthenticationFailed	Android, iOS	The response to the authentication challenge was incorrect. Example: This could be by an incorrect PIN code, which causes the authentication to fail.
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 it is having technical difficulties.
224	serverErrorLockedByAdmin	Android, iOS	The registration was locked by the server for a reason. Example: This could be caused by the registration being locked by an admin or customer support.
226	serverErrorLocked	Android, iOS	The registration is locked because either: The maximum number of authentication attempts was exceeded. The 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: This could be caused by activating fingerprint when the server only allows DEVICE and DEVICE:PIN .
232	serverErrorIllegalAuthFactor	Android, iOS	Tried 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 what is in the request from the client. Example: This could be caused by a new authentication session replacing the current authentication 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 cannot be parsed.
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 operation failed, but the client tried to finish the activation anyway.
249	serverErrorClientRequestTimeOutOfSync	Android, iOS	The request has an older timestamp than the previous request. Note: This means that either: The request was delayed on the way. The clock on the phone has been set back in time. The end-user needs to wait the CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD (given in milliseconds), then try again. Note: For further details, see the Encap server manual.
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 on the server side.
255	serverErrorAuthTokenValidationFailed	Android, iOS	Validation of the authentication token failed on the 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. Note: 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	A token with the wrong purpose has been used to perform an operation.
262	serverErrorInvalidAuthLevelForTokenRequest	Android, iOS	The token request requires two-factor authentication.
270	serverErrorGeofencingBoundaryValidationFailed	Android, iOS	The server evaluation of the country against the 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 whilst processing AppAttest data. Check the error message for more details.
281	serverErrorAppAttestTimeout	iOS	A timeout occurred whilst performing an 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	There is no key pair for the 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 whilst performing Play Integrity Attestation.

Recoverable errors

isRecoverableError indicates whether the error is recoverable or final in a finish operation:

• It will return true if the error is recoverable.
• It will return false if the error is not recoverable.

Android

The table below lists the recoverable errors for Android.

Code	Error name
105	clientErrorInvalidInputFormat
214	serverErrorAuthenticationFailed
1200	clientErrorAndroidBiometricPromptAuthenticationFailed
1202	clientErrorAndroidBiometricPromptAcquiredPartial
1203	clientErrorAndroidBiometricPromptAcquiredInsufficient
1204	clientErrorAndroidBiometricPromptAcquiredImagerDirty
1205	clientErrorAndroidBiometricPromptAcquiredTooSlow
1206	clientErrorAndroidBiometricPromptAcquiredTooFast
1207	clientErrorAndroidBiometricPromptUnexpectedHelpCode

iOS

The table below lists the recoverable errors for Android.

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..