Network errors - Elements SDK

Elements runs entirely in the browser up to the point your server receives a token, so a shopper’s own network conditions — offline, a flaky connection, or a blocked request — can interrupt tokenization independently of anything the gateway does.

TL;DR: a network_error with retryAllowed: true interrupts tokenization → offer a manual retry, and confirm the session hasn’t expired first.

When this happens

The shopper’s connection drops or times out while the card iframe is communicating with its own parent frame or with RadiumOne.
The page isn’t served over HTTPS (outside localhost), or crypto.randomUUID isn’t available — Elements requires a secure context.
A request between the parent page and the card iframe stalls long enough to hit the SDK’s own internal timeout (well over a minute, to give the iframe room to retry the bind on its own first) — this is rare, and distinct from a normal tokenization failure.

What you see

Signal	Value
Error type	`network_error`
Code	`network:request_timeout` (parent-to-iframe request stalled), or an iframe-relayed `network_error` from the bind attempt itself
`retryAllowed`	`true` for a transport failure — safe to retry
Insecure context	`ElementsError` `element:insecure_context`, thrown synchronously from `elements.create()`

What to do

Serve your checkout page over HTTPS

element:insecure_context means the page itself isn’t secure — fix the page’s protocol; there’s nothing to retry. localhost is exempt for local development.

Offer a retry for a transport failure

A network_error with retryAllowed: true is safe to retry — show a “try again” affordance rather than auto-resubmitting immediately.

try {
  const { token } = await elements.submit({ sessionId, sessionSecret, pubkeyJws });
} catch (err) {
  if (err.type === "network_error" && err.retryAllowed) {
    showRetryButton();
  } else {
    showError(err.customerMessage ?? "Payment could not be processed.");
  }
}

Check the session before retrying

If the shopper waited a while before retrying, confirm the session hasn’t expired first — see Handle expired sessions and card tokens. A network retry into an expired session just produces a second, different error.

Cap retries

Retry once or twice with a short backoff; after that, point the shopper at a page reload rather than retrying indefinitely.

Prevent it

Don’t self-host or proxy the SDK script or iframe through your own infrastructure — load it directly from RadiumOne’s CDN so the shopper’s browser talks to RadiumOne directly, without an extra network hop that can fail.

Handle Elements failing to load

Network failures at SDK load time, before any card field exists.

Install and load Elements

Secure-context and browser-support requirements.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Network errors - Elements SDK

When this happens

What you see

What to do

Prevent it

Handle Elements failing to load

Install and load Elements

​When this happens

​What you see

​What to do

​Prevent it

​Related

Handle Elements failing to load

Install and load Elements

When this happens

What you see

What to do

Prevent it

Related