Skip to main content
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:payment-gateway:checkout:tokenization-unavailable), a bind transport failure, urn:radiumone:elements:three-ds:challenge-timeout and urn:radiumone:elements: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.

Error codes

Every err.code is a URN, in one of three families: The field-level FieldErrorCode values on change events and in getState().errors (required, invalid_number, and so on) aren’t error codes. They stay short. See Card fields and events. The SDK exports SCRIPT_INTEGRITY_ERROR_CODE, which equals urn:radiumone:payment-gateway:auth:invalid-script-hash: the code submit() rejects with when the card iframe’s script attestation fails. Compare against the constant rather than retyping the URN.

Handling pattern

Three rules keep your handler correct as the list of codes grows:
  • Match the whole code. Compare err.code with the full URN. Never match a prefix or the text after the last :, because the same slug (for example not-found) appears in several namespaces.
  • Branch on retryAllowed, not on HTTP status. Two errors with the same status can need opposite handling. retryAllowed is the only retry signal.
  • Treat an unknown code as not retryable unless err.retryAllowed === true. The API can return new urn:radiumone:payment-gateway:* codes without an SDK release.
Show err.customerMessage when it’s present. Never show err.message: it’s developer English and can change.

Errors before initialization (no error code)

Thrown by loadRadiumOne() before RadiumOne.init() runs — plain Errors, not ElementsError. 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. For loader:integrity_unset with a test key, see Test keys with npm or React.

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.
Last modified on September 29, 2026