PrimerError

Errors thrown or returned from the Primer SDK can be cast to PrimerError. PrimerError is an enum containing information that will help you debug issues.

SWIFT

protocol PrimerErrorProtocol: CustomNSError, LocalizedError {
    var errorId: String { get }
    var exposedError: Error { get }
    var info: [String: Any]? { get }
    var diagnosticsId: String { get }
    var analyticsContext: [String: Any] { get }
}

​

Properties

Hide Properties

errorId · String · required

A unique error identifier.

description · String · required

The error description.

diagnosticsId · String · required

A unique diagnostics id for the given error.

recoverySuggestion · String

A recovery suggestion for the given error. In case it’s present, use it to try to recover from error.

analyticsContext · String

Additional context for analytics purposes.

List of the Component validation errors can be found here.

​

Exposed Error IDs and Error Codes

​

SDK Configuration Errors

Error ID	Description	Recovery Suggestion
missing-configuration	Returned when the internal SDK configuration is not present.	Check if you have an active internet connection.
invalid-client-token	Returned when the provided client token does not have a valid JWT format.	Ensure that the client token fetched from your backend is a valid client token (i.e. not null, not blank, is valid JWT and it comes from Primer)
expired-client-token	Returned when the provided client token has expired.	Avoid storing client tokens locally. Fetch a new client token to provide on when starting Primer.
missing-sdk-dependency	Returned when an SDK dependency is missing for a payment method type.	Follow the integration guide and include missing dependency.

​

Connectivity Errors

Error ID	Description	Recovery Suggestion
bad-network	Indicates a connectivity issue.	Check your internet connection and try again.

​

HTTP Errors

Error ID	Description	Recovery Suggestion
unauthorized	Indicates that the SDK’s request lacks valid authentication credentials (HTTP 401).	Check the server’s response to debug this error further.
client-error	Indicates an error caused by the SDK’s request (HTTP 4xx).	Check the server’s response to debug this error further.
server-error	Indicates an error caused by the server while processing the SDK’s request (HTTP 5xx).	Check the server’s response to debug this error further.

​

Payment Errors

Error ID	Description	Recovery Suggestion
payment-failed	Returned when processing a payment has failed.	Contact Primer and provide us with diagnostics id.
failed-to-create-payment	Returned when there is a failure in the internal SDK create payment call.	Contact Primer and provide us with diagnostics id.
failed-to-resume-payment	Returned when there is a failure in the internal SDK resume payment call.	Contact Primer and provide us with diagnostics id.
payment-cancelled	Returned when the payment was cancelled by the user.	N/A

​

Headless Universal Checkout Specific Errors

Error ID	Description	Recovery Suggestion
huc-initialization-failed	Returned when Headless Universal Checkout failed to initialize during the start call.	Ensure you are calling start method before calling this method.
invalid-raw-type-data	Returned when the wrong data type is being passed to the raw data setter.	Verify the data type being passed and correct it.
invalid-raw-data	Returned when the submit method was called without a prior call to the raw data setter.	Ensure setRawData is called with valid data before calling submit.

​

Payment Method Errors

​

Apple Pay

Error ID	Description	Recovery Suggestion
apple-pay-timed-out	Indicates that the Apple Pay request timed out.	Make sure you have an active internet connection and your Apple Pay configuration is correct.
unable-to-present-apple-pay	Indicates that the Apple Pay sheet failed to display.	Ensure device supports Apple Pay and that it is setup correctly. Check debug console for system errors.
apple-pay-no-cards-in-wallet	Indicates that no payment cards are configured in Apple Wallet.	Add a payment card to Apple Wallet before attempting to use Apple Pay.
apple-pay-device-not-supported	Indicates that the current device does not support Apple Pay.	Use a device that supports Apple Pay or choose an alternative payment method.
apple-pay-configuration-error	Indicates an issue with the Apple Pay merchant configuration.	Verify your Apple Pay merchant identifier and configuration. Contact support if the issue persists.
apple-pay-presentation-failed	Indicates that Apple Pay presentation failed for an unknown reason.	Try again or use an alternative payment method. Check the debug console for more detailed error information.

​

Klarna

Error ID	Description	Recovery Suggestion
klarna-user-not-approved	Returned when the user declined the Klarna transaction.	N/A
klarna-sdk-error	Returned when there is an internal error returned by the Klarna SDK.	N/A

​

iPay88

Error ID	Description	Recovery Suggestion
payment-failed	Returned when processing a payment has failed.	N/A
ipay-sdk-connection-error	Returned when there is an internal connection error returned by iPay88.	Check the network connection and retry.

​

nol Pay

Error ID	Description	Recovery Suggestion
nol-pay-sdk-error	Returned when there is an error returned by nol Pay. Errors can be distinguished by errorCode:	Specific recovery suggestions based on the errorCode:
	- A3300: Failed to init Transit SDK	- A3300: Ensure the Transit SDK is correctly initialized and try again.
	- A3301: Error on request parameter	- A3301: Contact Primer and provide us with diagnostics id.
	- A3302: Network error	- A3302: Check network connection and retry.
	- A3304: Failed to handle response payload	- A3304: Contact Primer and provide us with diagnostics id.
	- A3305: API call failed	- A3305: Contact Primer and provide us with diagnostics id.
	- A3310: Mobile phone does not support NFC	- A3310: Ensure the mobile phone supports NFC and retry.
	- A3311: NFC disabled on mobile phone	- A3311: Enable NFC on the mobile phone and retry.
	- A3312: Invalid NFC Tag	- A3312: Verify the NFC tag and retry.
	- A3313: NFC disconnected, user should hold Nol card until scanning finishes	- A3313: Hold the Nol card steady until scanning finishes.
	- A3314: NFC Command error	- A3314: Contact Primer and provide us with diagnostics id.

​

Session Create Error

Error ID	Description	Recovery Suggestion
failed-to-create-session	Returned when the Universal Checkout failed to create a session with 3rd party sides (e.g., Klarna, PayPal, etc.).	Ensure that the Payment method is configured correctly on the dashboard (https://dashboard.primer.io/)

​

General Errors

Error ID	Description	Recovery Suggestion
invalid-value	Returned when the required data for specific use cases has an invalid format or is missing.	Verify the data format and ensure all required data is provided.
invalid-client-session-value	Returned when the required client session data for specific use cases has an invalid format or is missing.	Verify the client session data format and ensure all required data is provided when calling Create a client session API call.
failed-to-update-client-session	Returned when the client session fails to update (e.g., selecting a payment method due to a surcharge being present, updating the billing address captured from Google Pay).	Check the session update parameters and retry.
unknown-error	Returned when the SDK catches an unmapped Exception.	Contact Primer and provide us with diagnostics id.