SDK errors (Android components)
Overview
The WeavrComponents SDK surfaces errors through ErrorResponse objects. Each ErrorResponse carries a numeric code and a string message. The code is either an HTTP status code from a server response or a WeavrErrorCode integer for SDK-level local failures.
WeavrErrorCode values
| Error Code | Integer Code | Description |
|---|---|---|
| unknown | -1 | A generic or unclassified SDK error. Used when no more specific code applies. |
| cantSetUIKey | 1001 | The SDK UI (programme) key is missing or could not be set. |
| cantSetSecureFieldsLength | 1002 | The secure field length could not be fetched or is not yet available. |
| cantRecreateKeyPairs | 1003 | The device key pair required for biometric enrolment could not be created or restored. |
| cantEnableSecurityService | 1004 | The biometric security service could not be initialised. |
| cantRetrieveSecurityServiceKey | 1005 | The server public key required to complete a secure operation could not be retrieved. |
| biometricsInvalidChallengeMetadata | 2001 | The challenge metadata (nonce, challenge ID, or integrity token) for biometric authentication is missing or invalid. |
Initialize components
UXComponents.initialize() throws an exception on failure rather than returning an ErrorResponse. Wrap the call in a try/catch to handle initialization errors.
UXComponents.psa.initialize() follows the same pattern and must be called before any biometric or PSA operations.
Set user token
UXComponents.setUserToken() reports failures through OnAssociateListener.onAssociateFailed(ErrorResponse), where code is one of:
- HTTP status codes: set by the server during token validation or API communication failures.
- -1: local or precondition failure (for example, the UI key is not set).
Common HTTP status codes
| Error Code | Description |
|---|---|
| 400 | Bad request. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
| 409 | Conflict. |
| 412 | Precondition failed. |
| 429 | Too many requests. |
| 5xx | Server error (500, 502, 503, 504, and others). |
Update device token
UXComponents.psa.updateDeviceToken() reports failures through WeavrResult.onFailure(ErrorResponse), where code is one of:
- HTTP status codes: set by the server.
- 1001 (cantSetUIKey): the UI key is missing.
Common HTTP status codes
| Error Code | Description |
|---|---|
| 400 | Bad request. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
| 409 | Conflict. |
| 412 | Precondition failed. |
| 429 | Too many requests. |
| 5xx | Server error (500, 502, 503, 504, and others). |
Tokenize secure fields
SecureEditText.createToken() and UXComponentGroup.createToken() report failures through OnTokenizeListener.onTokenizeFailed(ErrorResponse).
| Code | Description |
|---|---|
| 1002 (cantSetSecureFieldsLength) | The passcode length has not been fetched yet, or the input length does not match the required length. |
| 1001 (cantSetUIKey) | The UI key is missing. |
| -1 (unknown) | A runtime exception occurred during tokenisation, or the UI key is missing on a group-level tokenisation. |
| HTTP status codes | Server error during the tokenisation API call. |
Start biometric enrolment
UXComponents.psa.startPSAEnrollment() reports failures through WeavrPSAListener.onFailed(ErrorResponse).
All local failures use code -1 (unknown). Check the message property for the specific reason.
Common local failure scenarios
| Message | Description |
|---|---|
| "Biometric authentication is not available on this device." | The device does not support strong biometrics or none are enrolled. |
| "Consent screen closed" | The user dismissed the consent screen without confirming. |
| "Activity is not a FragmentActivity" | The activity passed to startPSAEnrollment does not extend FragmentActivity. |
Branding fetch or association errors that occur during the enrollment flow may also be reported with HTTP status codes and descriptive messages from the server.
Start biometric login
UXComponents.psa.startBiometricPsaLogin() reports failures through WeavrLoginListener.onFailed(ErrorResponse), where code is one of:
- HTTP status codes: set by the server during biometric login, verification, or password fallback API calls.
- SDK-level codes: for local precondition or runtime failures.
SDK-level error codes
| Code | Description |
|---|---|
| 1001 (cantSetUIKey) | The UI key is missing. |
| 1003 (cantRecreateKeyPairs) | No enrolment key is present on the device. Call startPSAEnrollment first. |
| 2001 (biometricsInvalidChallengeMetadata) | The Play Integrity token, challenge ID, nonce, or initial login response is missing or invalid. |
| 1005 (cantRetrieveSecurityServiceKey) | The server public key required for password fallback could not be retrieved. |
| -1 (unknown) | Local biometric authentication failed, the biometric prompt was cancelled, or an unclassified error occurred. |
Common HTTP status codes
| Error Code | Description |
|---|---|
| 400 | Bad request. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
| 409 | Conflict. |
| 412 | Precondition failed. |
| 429 | Too many requests. |
| 5xx | Server error (500, 502, 503, 504, and others). |
Common local failures
- Biometric hardware not available or no biometrics enrolled
- Play Integrity token not yet obtained (requires a moment after psa.initialize())
- Device enrolment key missing (device not enrolled—call startPSAEnrollment first)
- Cryptographic operation errors during password fallback
- Missing UI key or initialization state
Start biometric SCA challenge
UXComponents.psa.startChallenge() fetches challenge details and reports the result through WeavrPSASessionListener. After a successful challenge fetch, verify, or decline via the methods below.
Issue challenge errors
Reported via WeavrPSASessionListener.onFailed(ErrorResponse):
| Code | Description |
|---|---|
| 1001 (cantSetUIKey) | The UI key is missing. |
| -1 (unknown) | The server returned an empty response. |
| HTTP status codes | Server error during challenge retrieval. |
Verify challenge errors
verifyScaChallenge() reports failures through WeavrResult.onFailure(ErrorResponse):
| Code | Description |
|---|---|
| 1001 (cantSetUIKey) | The UI key is missing. |
| 2001 (biometricsInvalidChallengeMetadata) | The challenge ID or nonce is missing. |
| 1003 (cantRecreateKeyPairs) | The enrolment key is missing. |
| HTTP status codes | Server error during challenge verification. |
Decline challenge errors
declineLoginChallenge() reports failures through WeavrResult.onFailure(ErrorResponse), using the same codes as verify challenge above.
Start know-your-customer flow
UXComponents.kyc.startKYC() reports errors through two mechanisms.
Setup and API errors
Returned via OnKycCompleteListener.onKYCFailed(ErrorResponse):
| Code | Description |
|---|---|
| 1001 (cantSetUIKey) | The UI key is missing or blank. |
| -1 (unknown) | Local exception or precondition failure. |
| HTTP status codes | Server error during KYC access token retrieval. |
KYC SDK exceptions
Reported via KYCListeners.onWeavrKYCSDKErrorHandler(KYCException):
| Exception Type | Description |
|---|---|
| KYCException.API | An API error from the KYC SDK. Contains description, code, correlationId, errorCode, and errorName. |
| KYCException.Network | A network error from the KYC SDK. |
| KYCException.Unknown | An unexpected error from the KYC SDK. |
KYC SDK state failures
Reported via KYCListeners.onKYCSDKStateChangeHandler(KYCSDKState.Failed):
| State | Description |
|---|---|
| ApplicationNotFound | The KYC applicant could not be found. |
| ApplicantMisconfigured | The KYC applicant is misconfigured in the system. |
| InitialLoadingFailed | Initial loading of the KYC flow failed. |
| InvalidParameters | Invalid parameters were provided to the KYC flow. |
| NetworkError | A network error occurred during the KYC process. |
| Unauthorized | The user is not authorised; the token is invalid or could not be refreshed. |
| Unknown | An unexpected error occurred. |