Errors

How Cash App failures surface and what to do at each step.

How errors surface

1. Thrown errors - getSupportedAssets and createOrder reject with ConnectSdkError (stable code).
2. Events - cashApp:orderFailed and cashApp:orderExpired are not thrown errors, but you must handle them in UI; completion comes via cashApp:orderCompleted.

Branch on code, not on message text:

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

try {
  await client.cashApp.createOrder({
    /* amountFiat, destinationAsset, destinationChain */
  })
} catch (error) {
  if (!(error instanceof ConnectSdkError)) {
    throw error
  }

  switch (error.code) {
    case ConnectSdkErrorCode.SESSION_NOT_ACTIVE:
      await client.restartSession()
      break
    default:
      // API_ERROR / unknown - generic retry
      break
  }
}

client.cashApp.onOrderFailed(() => {
  // Not a thrown error - show failed UI
})

client.cashApp.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 assets	API / network failure	API_ERROR	Retry; keep Cash App selected
Create order	Session already completed	SESSION_NOT_ACTIVE	restartSession() first
Create order	Session not loaded	SESSION_REQUIRED	loadSession()
Create order	API rejection (amount, etc.)	API_ERROR	Show message; fix amount / retry
Waiting	Payment failed	cashApp:orderFailed	Failed UI; create a new order
Waiting	Order timed out	cashApp:orderExpired	Expired UI; create a new order
After success	Create again without restart	SESSION_NOT_ACTIVE	restartSession()

Amount below minAmountFiat 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 was in flight	Ignore; start again on the new session
API_ERROR	Assets / create HTTP failure	Retry; keep user on a safe step
CLIENT_DESTROYED	Client already destroyed	Create a new client