Documentation
Request a demo

Inspect Errors

The SDK uses typed errors to distinguish configuration, payment processing, feature, network, and validation issues and to indicate whether an operation can be retried. Error details and message keys provide additional context for handling failures consistently across the integration.

Errors

CheckoutError structure

Every SDK error (a method promise rejection or the error event) has a single typed shape:

interface

interface CheckoutError {
  type: CheckoutErrorType; // machine-readable code 
  message: string; // human-readable description (EN, for logs/debugging)
  retryable: boolean; // whether retrying the operation makes sense
  statusCode?: number; // HTTP status of the upstream response, when applicable
  featureType?: string; // feature type — for feature_error
  details?: Record<string, unknown>; // machine-readable details from the backend
}

SDK error types and their consequences

Type When it occurs Retryable Consequences and recommended actions
invalid_config The merchant configuration is incomplete/invalid. Usually an init() rejection (missing required fields, an invalid baseUrl / timeouts). A late case: the challenge.container selector does not resolve at the moment the 3-D Secure opens (then — an error event with details.challengeContainer). no The instance is not created (on init()). In the late case the challenge is not lost: the SDK opens its own modal (fallback). Fix the configuration — retries will not help.
invalid_submit_options submit() / retry() with invalid options: an empty paymentMethodSchemeId; a featureType that is not an initialised feature with collect(); no featureType given while several features are initialised; retry() without a prior submit(). no Rejected locally, before tokenization and any network activity — no one-time card token is spent, no payment attempt is created. Fix the call in your integration.
bridge_timeout The service bridge iFrame did not answer the handshake (within initTimeout) or an RPC call (within timeout). yes The current operation (init/submit/state request) did not complete. Check baseUrl, the network, content blockers/CSP. Retrying the operation is appropriate; for init() — call init() again.
network_error The bridge registered a transport/HTTP error (network down, connection reset). yes The operation did not complete; the payment state is unchanged or will be picked up by polling. Show "please try again", retry.
api_error The checkout API responded with an error payload (statusCode holds the upstream HTTP status, details holds machine-readable details). depends Act by statusCode: 4xx — most often a data/configuration problem (fix it), 5xx — temporary (retry later).
session_load_failed The session configuration could not be loaded during init(). depends init() rejects, the instance is not created. Check apiKey / merchantAccountId / paymentRequestId (in particular that the payment request exists and has not expired), then retry init().
process_failed Creating the payment attempt was rejected (the process request). Typical case: an unknown/invalid paymentMethodSchemeId → an upstream 422 passed through in statusCode / details. depends No attempt was created, no funds were charged. On a 422 — fix the pss_… id; otherwise show the error and let the customer retry.
feature_error A feature failed to initialize, collect data (collect, including field tokenization), or destroy itself. featureType points at the culprit; initFeature() rejects this way for an unknown type or a type outside the session. depends The feature is not active / the submit did not happen. If the feature's own init failed — a repeated initFeature(type) may succeed. For field configuration errors (a missing container of a required field) — fix the markup/config.
destroyed Any method call after destroy(). no The operation is not performed. Create a new instance via init().
unknown An unclassified error. depends Log it with details, show a generic message, allow a retry.

Field validation errors

Returned from hpf.validateAll() / field(type).validate() and delivered in the field's validity event.

{
  field,
  type,
  message,
  messageKey?,
  params?
}

All are retryable: true (the customer corrects the input).

Type Field When / possible messageKey
field_required any required The field is empty. messageKey: validation__is_required; message = "<field label> is required".
invalid_card_number cardNumber Invalid card number. validation__invalid_card_number.
invalid_expiry_date expiryDate Invalid expiry date. validation__invalid_month, validation__invalid_year or validation__invalid_format.
invalid_cvv cvv Invalid CVV/CVC. validation__invalid_cvv.
invalid_cardholder_name cardholderName Invalid cardholder name. validation__default_invalid_card_holder or validation__default_invalid_words_length.
validation_failed — A general failure of the validation procedure (not an input error of a specific field).
field_invalid any The generic "field is invalid" code when no more specific type applies.
📘

If a validator message did not match the dictionary, the error arrives without a messageKey, but only with a literal message. Map by messageKey when present, otherwise display message.

Low-level field and tokenisation errors

Originate inside the hosted fields feature (most often they reach you wrapped in a Checkout SDK-level feature_error; details / message preserve the original cause).

Type Retryable When it occurs / consequences
network_timeout yes A network timeout of a field/tokenisation operation. Retry.
invalid_config no Invalid field configuration (e.g. a container was not found). Fix the integration.
forbidden_origin no The page's domain is not among the allowed origins for this account. The fields will not mount. Add the domain in the account settings.
token_creation_failed no Card data tokenisation failed (may carry a statusCode). No payment attempt is created; check the data / retry the submit.
unknown_error yes An unclassified field-level error.

Updated about 19 hours ago

Did this page help you?