SDK and integration errors - Elements SDK

These are the codes you hit while wiring up Elements — a bad publishable key, an Element that isn’t mounted, a duplicate Element, or a call made out of order. Every one is an ElementsError (see Error object and handling); catch it and branch on err.code. Integration and SDK codes come from the SDK itself, synchronously or from submit(); Iframe-relayed codes are surfaced from inside the card iframe but arrive the same way, as err.code on the ElementsError submit() rejects with.

Integration and SDK codes

Thrown for programming errors and environment issues — fix the integration rather than retry, unless noted.

Code	Retryable	When	Merchant action
`api:invalid_key`	No	The publishable key is missing or not a string.	Pass your publishable key (r1pk_prod_, r1pk_test_ or r1pk_mock_*).
`api:secret_key_used`	No	A secret key (r1sk_*) was passed to the browser SDK.	Use your publishable key. Rotate the secret key if it was shipped to browsers.
`api:test_key_in_prod_build`	No	An r1pk_test_* key was used with the production bundle (js.radiumone.io).	Use an r1pk_prod_* key, or load the sandbox bundle (js-sandbox.radiumone.io) for test keys.
`api:prod_key_in_staging_build`	No	An r1pk_prod_* key was used with the sandbox bundle.	Use a test or mock key with the sandbox bundle, or load the production bundle.
`api:invalid_key_format`	No	The key prefix is not valid for this bundle, or a mock key suffix is not 1-32 characters of a-z, 0-9, _ or -.	Check the key for typos and that it matches the bundle’s channel.
`element:duplicate`	No	An Element of the same type already exists in this Elements group.	Destroy the existing Element first, or reuse it via Elements.getElement().
`element:insecure_context`	No	The page is not a secure context (crypto.randomUUID unavailable).	Serve the checkout page over HTTPS.
`element:destroyed`	No	mount() was called on a destroyed Element.	Create a new Element with Elements.create().
`element:container_not_found`	No	The selector passed to mount() matches no element.	Mount after the container is in the DOM; check the selector.
`element:not_mounted`	No	submit() was called while the card Element is not mounted.	Mount the Element and wait for its ready event before submitting.
`messenger:destroyed`	No	The Element was unmounted or destroyed while submit() was waiting for the iframe.	Keep the payment form mounted until submit() settles; remount and submit again.
`network:request_timeout`	No	The card iframe did not answer within 55 seconds (for example it failed to boot or was blocked).	Offer a retry; if it repeats, check that js.radiumone.io is not blocked by CSP or extensions.
`submit:legacy_signature`	No	submit() was called with the pre-2.0 form submit(sessionId, sessionSecret).	Call submit().
`submit:invalid_context`	No	The submit() argument is not an object.	Pass .
`submit:missing_session_id`	No	sessionId is missing or empty.	Pass session_id from POST /gateway/v1/sessions.
`submit:missing_session_secret`	No	sessionSecret is missing or empty.	Pass session_secret from POST /gateway/v1/sessions.
`submit:missing_pubkey_jws`	No	pubkeyJws is missing or not a compact JWS (three base64url segments).	Pass pubkey_jws from POST /gateway/v1/sessions unchanged (do not parse or re-serialise it).
`submit:in_progress`	No	Another submit() on the same Elements group has not settled.	Disable the pay button while submitting; ignore the duplicate call.
`submit:rate_limited`	No	submit() was called within 1 second of a successful submit().	Wait at least 1 second; normally a double-click after success.
`elements:no_elements`	No	submit() was called before any Element was created.	Create and mount a card Element first.
`required`	No	A created Element is empty. ElementsError.field names the Element type.	Ask the shopper to complete the field; gate the pay button on the change event’s valid flag.
`elements:missing_element`	No	Split fields were created without a cardNumber Element.	Create a cardNumber Element (or use the combined card Element).
`bind:invalid_response`	No	The bind succeeded but the response contained no token.	Treat as a failed payment attempt; create a new session and retry. Contact support if it repeats.
`bind:failed`	No	An unexpected non-SDK exception occurred during submit().	Offer a retry; report with the error message if it repeats.

For the specific symptoms these codes map to, see Fix publishable key errors (the api:* codes), Fix card fields that don’t render (the element:* codes), and Prevent double submission (submit:in_progress / submit:rate_limited).

Iframe-relayed codes

Surfaced from inside the card iframe. Treat an unrecognized value as a generic failure.

Code	Retryable	When	Merchant action
`overlay_blocked`	No	The card iframe is covered or obscured by other page content.	Close modals or overlays above the payment form, then retry.
`rate_limited`	No	The card iframe received a second submit within 1 second of a successful one.	Wait at least 1 second before submitting again.
`mock_key_in_prod_build`	No	A mock key reached a production card iframe.	Load the sandbox bundle for mock keys.
`expiry_missing`	No	Split fields: the expiry value did not reach the card-number iframe within 5 seconds.	Make sure a cardExpiry Element is created, mounted and filled; retry.
`cvv_missing`	No	Split fields: the CVV value did not reach the card-number iframe within 5 seconds.	Make sure a cardCvv Element is created, mounted and filled; retry.
`encryption_failed`	No	Card encryption failed inside the iframe.	Create a new session and retry; contact support if it repeats.
`unknown_error`	No	An unclassified failure inside the card iframe (for example the session context was rejected before submit).	Create a new session and retry; contact support if it repeats.
`bind_failed`	No	The bind HTTP call failed with no problem+json type.	Do not auto-retry. Create a new session if the shopper tries again.
`network_error`	Yes	The bind call got no HTTP response (network failure or 15 s timeout) after 3 attempts.	Offer the shopper a retry.
`submit:root_kid_untrusted`	No	pubkeyJws is attested by a root key this SDK build does not trust.	Check the session was created in the same environment (production vs sandbox) as the SDK bundle.
`submit:leaf_attestation_invalid`	No	The signing-key attestation inside pubkeyJws is malformed or its signature is invalid.	Create a new session. Make sure pubkey_jws is passed unchanged.
`submit:leaf_window_invalid`	No	The signing key’s validity window does not include now (also caused by a badly wrong device clock).	Create a new session and retry.
`submit:leaf_kid_mismatch`	No	pubkeyJws is signed by a different key than the one attested.	Create a new session. Make sure pubkey_jws is passed unchanged.
`submit:pubkey_sig_invalid`	No	The pubkeyJws signature does not verify.	Create a new session. Make sure pubkey_jws is passed unchanged.
`submit:pubkey_alg_unsupported`	No	pubkeyJws or its attestation uses an algorithm other than ES256.	Create a new session; contact support if it repeats.
`submit:pubkey_session_mismatch`	No	pubkeyJws belongs to a different session than sessionId.	Pass session_id and pubkey_jws from the same POST /gateway/v1/sessions response.
`submit:pubkey_expired`	No	pubkeyJws has expired.	Create a new session and retry.
`submit:pubkey_invalid_jwk`	No	The encryption key inside pubkeyJws is not a valid RSA-OAEP-256 key of at least 2048 bits.	Create a new session; contact support if it repeats.
`submit:pubkey_jws_malformed`	No	pubkeyJws could not be decoded.	Pass pubkey_jws unchanged; create a new session.

network_error here is the same signal covered in depth on Handle browser network errors; the rest resolve the same way as a tokenization failure — see Handle tokenization failures.

Next steps

Error object and handling

The ElementsError shape and the standard catch pattern.

Tokenization errors

Bind-time gateway errors from submit().

3D Secure errors

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

Handle failures overview

Find the right recovery guide by symptom.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

SDK and integration errors - Elements SDK

Integration and SDK codes

Iframe-relayed codes

Next steps

Error object and handling

Tokenization errors

3D Secure errors

Handle failures overview

​Integration and SDK codes

​Iframe-relayed codes

​Next steps

Error object and handling

Tokenization errors

3D Secure errors

Handle failures overview

Integration and SDK codes

Iframe-relayed codes

Next steps