Errors

How Exchange Pay failures surface and what to do at each step.

How errors surface

1. Thrown errors - getSupportedCurrencies, createOrder, getOrder, closeOrder reject with ConnectSdkError (stable code).
2. Events - exchangePay:orderExpired is not an error, but you must handle it in UI; completion comes via exchangePay:orderCompleted.

Branch on code, not on message text:

import { ConnectSdkError, ConnectSdkErrorCode } from '@swapped/connect-sdk'

try {
  await client.exchangePay.createOrder({
    /* provider, amount, token, blockchain */
  })
} catch (error) {
  if (!(error instanceof ConnectSdkError)) {
    throw error
  }

  switch (error.code) {
    case ConnectSdkErrorCode.SESSION_NOT_ACTIVE:
      await client.restartSession()
      break
    case ConnectSdkErrorCode.NO_ACTIVE_ORDER:
      // User landed on checkout without createOrder - go back to form
      break
    case ConnectSdkErrorCode.CLOSE_ACTIVE_ORDER_FAILED:
      // Retry close, or createOrder again (create clears previous when possible)
      break
    default:
      // API_ERROR / unknown - generic retry
      break
  }
}

client.exchangePay.onOrderExpired(() => {
  // Not a thrown error - show expired UI
})

When things fail in the flow

Step	What goes wrong	How you see it	What to do in UI
Load currencies	API / network failure	API_ERROR	Retry; keep provider selected
Create order	Session already completed	SESSION_NOT_ACTIVE	restartSession() first
Create order	Session not loaded	SESSION_REQUIRED	loadSession()
Create order	Session replaced mid-flight	SESSION_REPLACED	Ignore; start again on the new session
Create order	API rejection (amount, etc.)	API_ERROR	Show message; fix amount / retry
Checkout leave	Close API failed (canClose)	CLOSE_ACTIVE_ORDER_FAILED	Retry close or create a new order
Status / close	No order in memory	NO_ACTIVE_ORDER	Back to amount form / createOrder
Waiting	Order timed out	exchangePay:orderExpired	Expired UI; create a new order
After success	Create again without restart	SESSION_NOT_ACTIVE	restartSession()

Amount below minAmountFiat or above maxAmountFiat should be blocked in the form before createOrder. Provider-side amount errors still surface as API_ERROR.

Error code reference

Code	When it happens	What to do
SESSION_REQUIRED	No loaded session	Call loadSession()
SESSION_NOT_ACTIVE	Session cannot accept a new payment	restartSession() before createOrder
SESSION_REPLACED	Session was replaced while create/close was in flight	Ignore; start again on the new session
NO_ACTIVE_ORDER	getOrder / closeOrder without an active order	Call createOrder first
CLOSE_ACTIVE_ORDER_FAILED	Provider close request failed	Retry close, or create a new order
API_ERROR	Currencies / create / status / close HTTP failure	Retry; keep user on a safe step
CLIENT_DESTROYED	Client already destroyed	Create a new client

canClose === false providers (Bybit, OKX): do not treat “no cancel button” as an error - skip close UI and create a new order when needed.