> ## Documentation Index
> Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.

# Network errors - Elements SDK

> How to handle a network failure during submission, and when it's safe to retry.

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.

<Info>
  TL;DR: a `network_error` with `retryAllowed: true` interrupts tokenization → offer a manual retry, and confirm the session hasn't expired first.
</Info>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.

    ```js theme={null}
    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.");
      }
    }
    ```
  </Step>

  <Step title="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](/elements/handle-failures/expired-sessions-and-tokens). A network retry into an expired session just produces a second, different error.
  </Step>

  <Step title="Cap retries">
    Retry once or twice with a short backoff; after that, point the shopper at a page reload rather than retrying indefinitely.
  </Step>
</Steps>

## 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.

## Related

<Columns cols={2}>
  <Card title="Handle Elements failing to load" icon="triangle-alert" href="/elements/handle-failures/sdk-fails-to-load">
    Network failures at SDK load time, before any card field exists.
  </Card>

  <Card title="Install and load Elements" icon="download" href="/elements/install-and-load">
    Secure-context and browser-support requirements.
  </Card>
</Columns>