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
Machine-readable error code — branch on this, never on
message.Match codes exactly; do not prefix-match or normalise them.Shopper-safe message supplied by the gateway. Display verbatim when present; otherwise use your own copy keyed on
code.The
ElementType a field validation error belongs to. Present only on field validation errors raised by submit().Suggested wait in seconds before retrying, from the gateway. Informational (for button copy), not a guarantee.
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.Error codes
Everyerr.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.codewith the full URN. Never match a prefix or the text after the last:, because the same slug (for examplenot-found) appears in several namespaces. - Branch on
retryAllowed, not on HTTP status. Two errors with the same status can need opposite handling.retryAllowedis the only retry signal. - Treat an unknown code as not retryable unless
err.retryAllowed === true. The API can return newurn:radiumone:payment-gateway:*codes without an SDK release.
err.customerMessage when it’s present. Never show err.message: it’s developer English and can change.
Errors before initialization (no error code)
Thrown byloadRadiumOne() 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.