SDK errors (iOS components)
Overview
The WeavrComponents SDK surfaces errors through ErrorResponse objects (with optional numeric code values) or module-specific enums. This page provides a comprehensive reference for error codes returned by each public method.
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 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 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 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 enrolment
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 initialised 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. Sign in the user 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 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:
| Error Code | 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 | KYC initialization failed. |
invalidParameters | Invalid parameters provided to the KYC flow. |
unauthorized | User is not authorized to perform KYC. |
applicantNotFound | The applicant could not be found. |
applicantMisconfigured | The applicant is misconfigured in the system. |
networkError | Network connection error during KYC process. |
unexpectedError | An unexpected error occurred that doesn't fit other categories. |