Troubleshooting and SDK errors (Android)
This page covers errors from both of our Android SDKs. The first sections describe the Components SDK (WeavrComponents), which surfaces errors through ErrorResponse objects. The final section covers the Push ProvisioningPush Provisioning A method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta. SDK, which wraps errors in WPPException.
Install
Gradle can't find com.sumsub.sns:idensic-mobile-sdk
Gradle fails with Could not find com.sumsub.sns:idensic-mobile-sdk:<version> when your project is missing Sumsub's Maven repository. Our identity-verification dependency is hosted there rather than on Maven Central.
Add the repository to settings.gradle:
repositories {
google()
mavenCentral()
maven { url "https://maven.sumsub.com/repository/maven-public/" }
}
See Configure repositories for the full install steps.
WeavrErrorCode values
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.
| 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 (program) 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 enrollment could not be created or restored. |
| cantEnableSecurityService | 1004 | The biometric security service could not be initialized. |
| 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. |
Initialise 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 PSAPSA Push Step-up Authentication - the mechanism in our mobile SDKs that delivers a step-up challenge to an enrolled device as a push notification and verifies it with the user's device biometrics. PSA covers device enrollment, biometric login, and biometric verification of SCA challenges for sensitive operations such as outgoing wire transfers or accessing card details. Exposed as `UXComponents.psa` on iOS and Android and via `initializePSA` on React Native. 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 keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own 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 keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own 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 keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. is missing. |
| -1 (unknown) | A runtime exception occurred during tokenizationTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants., or the UI keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. is missing on a group-level tokenizationTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants.. |
| HTTP status codes | Server error during the tokenizationTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. API call. |
Start biometric enrollment
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.
Troubleshooting ENROLLMENT_FAILED: Invalid Origin (HTTP 403)
The SDK maps all HTTP 403 responses across the entire SDK to Invalid Origin. During enrollment, the enrollment request is the first one made, so a misconfigured Play Integrity setup typically surfaces there first, but the same root cause can produce this message from other calls (login, SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). challenges, and others).
| Cause | How to confirm | Fix |
|---|---|---|
| Play Integrity API not enabled in GCP | Check GCP Console → APIs & Services | Enable the Play Integrity API |
| App not linked in Google Play Console | Check Play Console → Release → App integrity | Link your GCP project |
Wrong uiKey for the environment | Compare the key in use against the Weavr portal | Use the correct key for the environment (Production or Sandbox) |
| Sideloaded or debug APK on production | Sandbox works, production fails | Test via Google Play Internal Testing, not a direct APK install |
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 keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. is missing. |
| 1003 (cantRecreateKeyPairs) | No enrollment 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 canceled, 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 psaPSA Push Step-up Authentication - the mechanism in our mobile SDKs that delivers a step-up challenge to an enrolled device as a push notification and verifies it with the user's device biometrics. PSA covers device enrollment, biometric login, and biometric verification of SCA challenges for sensitive operations such as outgoing wire transfers or accessing card details. Exposed as `UXComponents.psa` on iOS and Android and via `initializePSA` on React Native..initialize())
- Device enrollment key missing (device not enrolled-call startPSAEnrollment first)
- Cryptographic operation errors during password fallback
- Missing UI keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. or initialization state
Start biometric SCA challenge
UXComponents.psa.startChallenge() fetches Strong Customer Authentication (SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).) 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 keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own 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 keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. is missing. |
| 2001 (biometricsInvalidChallengeMetadata) | The challenge ID or nonce is missing. |
| 1003 (cantRecreateKeyPairs) | The enrollment 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 the preceding verify challenge table.
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 keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. is missing or blank. |
| -1 (unknown) | Local exception or precondition failure. |
| HTTP status codes | Server error during KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. access token retrieval. |
KYC SDK exceptions
Reported via KYCListeners.onWeavrKYCSDKErrorHandler(KYCException):
| Exception Type | Description |
|---|---|
| KYCException.API | An API error from the KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. SDK. Contains description, code, correlationId, errorCode, and errorName. |
| KYCException.Network | A network error from the KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. SDK. |
| KYCException.Unknown | An unexpected error from the KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. SDK. |
KYC SDK state failures
Reported via KYCListeners.onKYCSDKStateChangeHandler(KYCSDKState.Failed):
| State | Description |
|---|---|
| ApplicationNotFound | The KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. applicant could not be found. |
| ApplicantMisconfigured | The KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. applicant is misconfigured in the system. |
| InitialLoadingFailed | Initial loading of the KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. flow failed. |
| InvalidParameters | Invalid parameters were provided to the KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. flow. |
| NetworkError | A network error occurred during the KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. process. |
| Unauthorized | The user is not authorized; the token is invalid or could not be refreshed. |
| Unknown | An unexpected error occurred. |
Push provisioning SDK
The Android Weavr Provisioning SDK wraps errors within a class called WPPException.
This exception is not thrown, but rather wrapped within an Outcome.Failure type.
The main way to identify which error occurred is via the WPPException.code and WPPException.domain properties.
The first one is an integer representing which error occurred, while the second identifies which subsystem created the error.
Additionally, extra data may be included, and an exception may occur in WPPException.extraData and WPPException.cause.
Push provisioning error codes
All potential error codes are gathered in WeavrSDKErrorCodes.
The following table lists the error codes the SDK may surface through Outcome.Failure:
| Error code | Scenario | Recommended action |
|---|---|---|
SDK_NOT_INITIALISED (1000) | Initialization missing | Initialize in your app before any call. |
CARD_NOT_PROVISIONED (1001) | Attempting to set default for unknown card | Prompt user to add card first. |
NETWORK_ERROR (1002) | Connectivity issues | Retry with backoff; surface offline state. |
CARD_NOT_ELIGIBLE (1003) | Backend flagged card ineligible | Show user-friendly message; escalate to issuer. |
COULD_NOT_FETCH_PROVIDER (1004) | Missing routing data | Validate backend response and provisioning config. |
MISSING_* (2001–2007) | AddToWalletButton missing parameters | Ensure all fields set before user taps. |
GOOGLE_PAY_* (3001–3006) | Google Pay SDK issues | Provide fallback or retry guidance. |
SETUP_ERROR (4001) | Local app misconfiguration | Revisit installation steps. |
INVALID_ACTIVITY (5001) | Non-FragmentActivity host | Use AppCompatActivity or attach fragment correctly. |
UNKNOWN_ERROR (-1) | Unmapped exception | Capture logs for support. |