Troubleshooting and SDK errors (iOS)
This page covers errors from both of our iOS SDKs. The first sections describe the Components SDK (WeavrComponents), which surfaces errors through ErrorResponse objects or module-specific enums. 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 surfaces errors through WPPError.
Initialize components
UXComponents.initialize returns an ErrorResponse whose code contains one of these WeavrErrorCode values:
| Error Code | Description | Integer Code |
|---|---|---|
cantSetUIKey | Unable to set 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. during initialization. | 1001 |
cantSetSecureFieldsLength | Unable to set secure fields length. | 1002 |
cantRecreateKeyPairs | Unable to recreate key pairs. | 1003 |
cantEnableSecurityService | Unable to enable security service. | 1004 |
cantRetrieveSecurityServiceKey | Unable to retrieve security service key. | 1005 |
Set user token
UXComponents.setUserToken returns an ErrorResponse where code is one of:
- HTTP status codes: set by
DataResponseErrorduring token validation or API communication failures. -1: local or precondition failure (for example, 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. 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 returns an ErrorResponse where code is one of:
- HTTP status codes: as specified by the server.
-1: local or precondition failure (for example, 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 device fingerprint).
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). |
Start biometric enrollment
UXComponents.psa.startEnrollment returns a BiometricsEnrollmentResult representing the outcome of the enrollment flow. This enum can be any case of:
| Case | Description |
|---|---|
completed | The enrollment flow completed successfully. |
initialisationError(error:) | The SDK was not properly initialized when the enrollment flow was triggered. The associated error value is a BiometricsInitializationError specifying what went wrong. |
cryptographyError(error:) | An error occurred in the cryptography module while attempting to create the enrollment. The associated error value is a BiometricsCryptographyError specifying what went wrong. |
failedBiometricsChallenge | The user failed the biometrics challenge. |
unauthorized | The token provided is not authorized. Log the user in again and provide a new token. |
userDoesNotConsent | The user did not consent to enroll by tapping the cancel button. |
failedToLoadBrand | The flow failed to launch because the biometrics configuration could not be fetched. |
noPhoneNumberAvailable | The user does not have an associated phone number. |
noBiometricsAvailable(hardwareSupportsBiometrics:) | Biometrics are not available on the device. If hardwareSupportsBiometrics is true, Face ID or Touch ID is not enrolled but the device supports it. If false, the device does not support any biometrics. |
challengeFailed(cause:) | The enrollment challenge failed. For example, the OTP expired or an invalid value was provided. The associated cause string describes the reason. |
Start biometric login
UXComponents.psa.startBiometricPSALogin returns an ErrorResponse where code is one of:
- HTTP status codes: set by
DataResponseErrorduring biometric login, verification, or association API calls. -1: local failures (for example, biometric authentication failures, crypto errors, or missing UI state).
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 authentication failed (for example, Face ID or Touch ID rejected)
- Cryptographic operation errors
- 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
- Device biometric capability unavailable
Start biometric SCA challenge
UXComponents.psa.startBiometricsChallenge provides a BiometricsChallengeResult in a completion callback. BiometricsChallengeResult includes a state property that defines the challenge state once the method completes.
The state can be any of:
| State | Description |
|---|---|
completed | Challenge completed successfully. |
declined | Challenge declined by the user. |
noSessionAvailable | No session was present when the challenge was initiated. |
invalidPassword | The user failed the biometrics check, and introduced an invalid password in the password fallback. |
failedToDisplay(message: String) | Couldn't display the biometrics challenge. Includes a message with an internal reason. |
cryptoError(message: String) | An error occurred in the cryptography module. Includes a message with an internal reason. |
serverError(flow: BiometricsChallengeFlow, error: ErrorResponse) | There was an unexpected error while communicating with the server. The BiometricsChallengeFlow enum identifies in which part of the biometrics flow the error occurred, and the error specifies the code and message obtained. |
Start know-your-customer flow
UXComponents.kyc.startKyc reports errors through the KYCEvent.kycError callback, which includes a KYCErrorCause value describing the failure.
| Error Cause | Description |
|---|---|
initializationError | 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. initialization failed. |
invalidParameters | Invalid parameters 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. |
unauthorized | User is not authorized to perform 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.. |
applicantNotFound | The applicant could not be found. |
applicantMisconfigured | The applicant is misconfigured in the system. |
networkError | Network connection 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. process. |
unexpectedError | An unexpected error occurred that doesn't fit other categories. |
Push provisioning SDK
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 reports errors through WPPError, an error type returned from the SDK's provisioning operations.
WPPError
WPPError contains the following properties:
| Property | Type | Description |
|---|---|---|
description | String | A description providing further details of how the error occurred. |
reason | String | A description of the underlying reason for the error. More in depth than the description. |
domain | WeavrProvisioningErrorDomain | A domain of the error, providing an approximate category of where the error occurred. |
underlyingErrorCode | Int? | The error code that our SDK received from the platform. |
errorCode | WeavrProvisioningErrorCode | The error code as defined by our SDK. |
Push provisioning error codes
The enum WeavrProvisioningErrorCode outlines a series of error codes that the SDK can surface when something goes wrong. As per the following table:
| Error Code | Description | Integer Code |
|---|---|---|
cardNotEligibleForProvisioning | The card is not eligible for provisioning. | 1003 |
cantFindProviderToUse | Couldn't find the provider to use. This can occur when there's a problem obtaining the provider from the API, e.g. a client error or server error. | 1004 |
emptyEntries | No card entries provided by the user. | 1005 |
userCancelled | The user canceled the flow. | 1006 |
unauthorized | The token is not present or is rejected during provisioning. | 2002 |
missingCardId | The card Id is empty. | 2003 |
missingCardLastFourDigits | The last four digits of the card provided is empty. | 2005 |
missingCardholderName | The card holder name of the card provided is empty. | 2006 |
missingCardDescription | The card description of the card provided is empty. | 2007 |
cantBeAddedToAppleWallet | Couldn't add the card to Apple Wallet. | 3001 |
cantFindViewController | Couldn't find the top most view controller to display the provisioning view controllers. | 5001 |
cantObtainPaymentPassRequestConfiguration | The payment pass request configuration needed by Apple Wallet to provision the card couldn't be created. | 5002 |
cantCreateProvisioningExtensionPaymentPassEntry | The SDK couldn't create the extension payment pass entry needed by Apple Wallet. | 5003 |
cantCreateProvisioningExtensionPaymentPassRequest | The SDK couldn't create the payment pass request to add the card selected by the user to Apple Wallet. | 5004 |
unknown | An unknown error occurred. | -1 |