Skip to main content
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

List of the Component validation errors can be found here.

​
Exposed Error IDs and Error Codes

​
SDK Configuration Errors

Error IDDescriptionRecovery Suggestion
missing-configurationReturned when the internal SDK configuration is not present.Check if you have an active internet connection.
invalid-client-tokenReturned 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-tokenReturned 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-dependencyReturned when an SDK dependency is missing for a payment method type.Follow the integration guide and include missing dependency.

​
Connectivity Errors

Error IDDescriptionRecovery Suggestion
bad-networkIndicates a connectivity issue.Check your internet connection and try again.

​
HTTP Errors

Error IDDescriptionRecovery Suggestion
unauthorizedIndicates that the SDK’s request lacks valid authentication credentials (HTTP 401).Check the server’s response to debug this error further.
client-errorIndicates an error caused by the SDK’s request (HTTP 4xx).Check the server’s response to debug this error further.
server-errorIndicates 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 IDDescriptionRecovery Suggestion
payment-failedReturned when processing a payment has failed.Contact Primer and provide us with diagnostics id.
failed-to-create-paymentReturned when there is a failure in the internal SDK create payment call.Contact Primer and provide us with diagnostics id.
failed-to-resume-paymentReturned when there is a failure in the internal SDK resume payment call.Contact Primer and provide us with diagnostics id.
payment-cancelledReturned when the payment was cancelled by the user.N/A

​
Headless Universal Checkout Specific Errors

Error IDDescriptionRecovery Suggestion
huc-initialization-failedReturned when Headless Universal Checkout failed to initialize during the start call.Ensure you are calling start method before calling this method.
invalid-raw-type-dataReturned when the wrong data type is being passed to the raw data setter.Verify the data type being passed and correct it.
invalid-raw-dataReturned 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 IDDescriptionRecovery Suggestion
apple-pay-timed-outIndicates 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-payIndicates 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-walletIndicates 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-supportedIndicates 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-errorIndicates 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-failedIndicates 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 IDDescriptionRecovery Suggestion
klarna-user-not-approvedReturned when the user declined the Klarna transaction.N/A
klarna-sdk-errorReturned when there is an internal error returned by the Klarna SDK.N/A

​
iPay88

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

​
nol Pay

Error IDDescriptionRecovery Suggestion
nol-pay-sdk-errorReturned 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 IDDescriptionRecovery Suggestion
failed-to-create-sessionReturned 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 IDDescriptionRecovery Suggestion
invalid-valueReturned 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-valueReturned 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-sessionReturned 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-errorReturned when the SDK catches an unmapped Exception.Contact Primer and provide us with diagnostics id.