Error object and handling - Elements SDK

Every error elements.submit() and threeDS.authenticate()/handle()/resume() throw is an ElementsError — you detect one the same way everywhere: catch it, check err.name, then branch on the stable err.code. The only exception is loadRadiumOne() itself, which can throw a plain Error before RadiumOne.init() ever runs (see below). 3D Secure result statuses (declines, EXPIRED, and so on) are not errors — see Authentication results for those.

`ElementsError`

string

required

Machine-readable error code — branch on this, never on message.Match codes exactly; do not prefix-match or normalise them.

string

Shopper-safe message supplied by the gateway. Display verbatim when present; otherwise use your own copy keyed on code.

string

The ElementType a field validation error belongs to. Present only on field validation errors raised by submit().

number

Suggested wait in seconds before retrying, from the gateway. Informational (for button copy), not a guarantee.

boolean

Whether retrying the same operation can succeed. The only retry signal — never infer retryability from the HTTP status or type.true for a retryable gateway error (for example urn:radiumone:checkout:tokenization-unavailable), a bind transport failure, urn:radiumone:three-ds:challenge-timeout and urn:radiumone:three-ds:cancelled. false or absent means do not retry the same session; start a new one or fix the input as the code indicates.

ElementsErrorType

required

Broad error category. See ElementsErrorType.

Handling pattern

try {
  const { token } = await elements.submit({ sessionId, sessionSecret, pubkeyJws });
} catch (err) {
  if (err.name === "ElementsError" || err.name === "ThreeDSCancelledError") {
    showError(err.customerMessage ?? "Payment could not be processed.");
    if (err.retryAllowed !== true) disableRetry();
  } else {
    throw err; // unexpected — don't swallow
  }
}

Errors before initialization (no error code)

Thrown by loadRadiumOne() before RadiumOne.init() runs — plain Errors, not ElementsError.

Class	When	Merchant action
`Error`	Missing key, secret key (r1sk_*), or unrecognised key prefix — checked before the CDN script is loaded.	Fix the publishable key.
`Error`	The CDN script failed to load, failed SRI, or did not load within 10 seconds.	Check script-src CSP and network; loadRadiumOne() can be called again.
`Error`	The npm package was built for the other channel (for example a test key with the production package). Message contains `loader:integrity_unset`.	Install the package matching the key’s environment.

These are thrown synchronously by loadRadiumOne() itself — before RadiumOne.init() runs, so there’s no ElementsError yet, only a plain Error. See Handle Elements failing to load and Fix publishable key errors for recovery steps.

Next steps

Integration and SDK errors

Codes thrown by the SDK itself and relayed from the card iframe.

Tokenization errors

Bind-time gateway errors from submit(), plus charge-time token errors.

3D Secure errors

Codes from authenticate(), handle(), and resume().

Handle failures overview

Find the right recovery guide by symptom for every error across these pages.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Error object and handling - Elements SDK

`ElementsError`

Handling pattern

Errors before initialization (no error code)

Next steps

Integration and SDK errors

Tokenization errors

3D Secure errors

Handle failures overview

​ElementsError

​Handling pattern

​Errors before initialization (no error code)

​Next steps

Integration and SDK errors

Tokenization errors

3D Secure errors

Handle failures overview

`ElementsError`

Handling pattern

Errors before initialization (no error code)

Next steps