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 an ErrorResponse where code is typically -1. Failure cases are driven by branding or association prerequisites and surface as descriptive message values.
Common failure scenarios
- Missing association
- Branding fetch errors
- Biometric enrollment precondition failures
Check the message property of the ErrorResponse for detailed error information.
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. |