Errors and edge cases

The SDK draws a line between two kinds of failure.

Flow-level failures are expected outcomes. The on-chain flows (coinlist.superstate.execute, coinlist.tokenSale.execute, coinlist.superstate.authorizeWallet, coinlist.ondo.prepareBuy, coinlist.ondo.prepareSell, coinlist.ondo.executeSwap) return a tagged result rather than throwing, so you handle them with a branch, not a catch.
Thrown errors are for genuinely exceptional conditions, such as calling an authenticated method without a session.

const result = await coinlist.superstate.execute({ /* ... */ });

if (result.type === "success") {
  showReceipt(result.swapTxHash, result.outputAmount);
} else {
  handleSwapError(result.error); // result.error.step tells you where it stopped
}

Wallet errors

WalletError is the shared vocabulary for anything the user’s wallet does. It appears as the cause on any step that asked the wallet to sign or send.

`type`	Meaning	Suggested handling
`user_rejected`	The user dismissed the wallet prompt.	Not an error state. Return the user to the previous step so they can retry.
`insufficient_funds`	The wallet cannot cover the amount or the gas.	Tell the user what is short. Retrying without a top-up will fail again.
`contract_reverted`	The transaction reverted on-chain. Carries a `reason` string.	Surface a generic message and log `reason`. Usually a stale quote or a failed eligibility check.
`timeout`	The receipt did not arrive in time. Carries the `hash`.	The transaction may still confirm. Link the user to an explorer with `hash` rather than prompting a resend.
`unknown`	Unclassified. Carries the original `cause`.	Show a generic error and log `cause`.

If you drive a wallet yourself, classifyWalletError(error, { hash }) turns a raw thrown wallet error into a typed WalletError. Pass hash when you are awaiting a receipt so a timeout can be reported against the right transaction.

Superstate swap errors

coinlist.superstate.execute returns SwapExecutionError, tagged by step.

`step`	What happened
`status-check`	Reading the swap contract’s status failed.
`swap-stopped`	The swap contract is not currently accepting swaps.
`allowance-check`	Reading the current ERC-20 allowance failed.
`approval`	The user did not approve the ERC-20 spend. Carries a `WalletError` cause.
`approval-reverted`	The approval transaction reverted on-chain.
`swap`	The user did not sign the swap transaction. Carries a `WalletError` cause.
`swap-reverted`	The swap transaction reverted on-chain.

The wallet is only asked to sign after all read-only checks pass, so a user never signs a transaction the swap would revert on for a reason the SDK could have caught first.

Token sale errors

coinlist.tokenSale.execute returns TokenSaleExecutionError.

`step`	What happened
`allowance-check`	Reading the current ERC-20 allowance failed.
`allowance-reset`	The user did not sign the reset to zero. Carries a `WalletError` cause.
`allowance-reset-reverted`	The reset transaction reverted on-chain.
`approval`	The user did not approve the ERC-20 spend. Carries a `WalletError` cause.
`approval-reverted`	The approval transaction reverted on-chain.
`participation`	The approval succeeded but recording the participation failed. Carries `approvalTxHash`.

The participation step is the one to handle carefully. The user’s funds are already approved on-chain, but the participation was not recorded. Keep approvalTxHash, surface it to the user, and reconcile rather than asking them to approve a second time.

Allowance resets

The allowance-reset steps only occur when the wallet already holds a non-zero allowance that must be set to zero first. USDT-style tokens reject a non-zero to non-zero approve(), so the SDK resets before re-approving. This means those users see two wallet prompts instead of one, which is worth reflecting in your loading copy.

Ondo swap errors

Placing an Ondo order is two calls, so it has two error types. coinlist.ondo.prepareBuy and coinlist.ondo.prepareSell both return OndoSwapPreparationError - every arm names a remedy rather than a direction, and an unsupported chain, a refused approval and a build that would not complete are fixed the same way whichever token was being approved.

`step`	What happened
`unsupported-chain`	The offer names no CoinList swap contract on the requested chain. Carries the `chain`. Both Ondo checkouts surface this as a flow-level `error` state before any step runs.
`allowance-check`	Reading the current ERC-20 allowance failed.
`approval`	The user did not approve the ERC-20 spend. Carries a `WalletError` cause.
`approval-reverted`	The approval transaction reverted on-chain.
`insufficient-allowance`	The approval mined, but the backend still reads a short allowance. Usually its RPC node lagging a block. Retry, do not re-approve.
`build-transaction`	Building the transaction failed.

coinlist.ondo.executeSwap returns OndoSwapExecutionError, for either direction.

`step`	What happened
`quote-expired`	The built calldata is at or past its deadline. Build a fresh transaction.
`swap`	The user did not sign the swap transaction. Carries a `WalletError` cause.
`swap-reverted`	The swap transaction reverted on-chain.

quote-expired is a refusal to broadcast rather than a failure of a broadcast. It would revert on-chain and cost the user gas, and it is fixed by building a fresh transaction rather than by retrying the same one.

spender-mismatch was removed in v0.12.0. The spender now comes off the offer’s swapContracts, and the backend compares the built transaction’s destination to the contract it serves there, so a third comparison would check one source against itself. A wrong spender still surfaces, as insufficient-allowance.

Wallet authorization errors

coinlist.superstate.authorizeWallet returns WalletAuthorizationError. See Superstate Swap for the full table and the progress phases.

Wallet connection errors

ConnectWalletError carries a code, a message, and a retryable flag. Respect retryable when deciding whether to offer a retry button.

`code`	Meaning
`not_authenticated`	No CoinList session. Send the user through OAuth first.
`user_rejected`	The user dismissed the connection prompt.
`wallet_not_whitelisted`	The wallet is not allowlisted for this offer. See Superstate Swap.
`max_wallets_reached`	The user has already connected the maximum number of wallets for the offer.
`unknown`	Unclassified.

OAuth errors

useCompleteOAuth fails with a CompleteOAuthFailureReason, which is either complete_request_failed or one of the client-side reasons below.

Reason	Meaning
`user_canceled`	The user declined authorization.
`missing_state`	No `state` parameter came back on the redirect.
`invalid_state`	The returned `state` did not match the stored value. Treat as a possible CSRF attempt and restart sign-in.
`missing_code`	No authorization code on the redirect.
`missing_code_verifier`	The stored PKCE verifier was gone, usually because storage was cleared mid-flow.
`complete_request_failed`	The code-for-token exchange against your backend failed.

KYC token errors

useKycToken fails with not-authenticated when there is no session, or generic-error for everything else.

Thrown errors

Error	When
`NotAuthenticatedError`	An authenticated method was called without a valid session.
`HttpError`	The API refused a request. Carries the `response`; read the body’s error code with `apiErrorCode(error)`.
`ValidationError`	Arguments the type system accepts but the API cannot, such as an Ondo quote sized by both `tokenAmount` and `notionalValue`, or an unrecognized chain string.
`CoinListClientInitializationError`	`useCoinList()` was called outside `CoinListProvider`.
`NotImplementedError`	A surface that is not available in the current environment was called.
`WritableSessionStoreRequiredError`	`auth.completeOAuth` or `auth.logout` was called on a `CoinListServer` with a read-only session store. From `@coinlist-co/react/server`.

Reading an API error code

HttpError is what every API call rejects with when the backend refuses a request, so it is the only way to catch a 4xx by type. Catching by type is half of it - telling two 422s apart takes the code inside the body, which is what apiErrorCode reads. Below, insufficient_allowance is the code POST /v1/ondo/swap/buy and POST /v1/ondo/swap/sell return when the wallet has not approved the swap contract for the amount. prepareBuy and prepareSell already absorb it into their insufficient-allowance step, so you only write this when you call a builder yourself.

import { apiErrorCode, HttpError } from "@coinlist-co/react/universal";

try {
  await coinlist.ondo.buildBuyTransaction(params);
} catch (error) {
  if (error instanceof HttpError) {
    switch (apiErrorCode(error)) {
      case "insufficient_allowance":
        return showApprovalPrompt();
      default:
        return showGenericError();
    }
  }
  throw error;
}

Get started

Offers and requirements

Flows

Reference

Wallet errors

Superstate swap errors

Token sale errors

Allowance resets

Ondo swap errors

Wallet authorization errors

Wallet connection errors

OAuth errors

KYC token errors

Thrown errors

Reading an API error code

Next steps

Allowlist a wallet

Package overview

​Wallet errors

​Superstate swap errors

​Token sale errors

​Allowance resets

​Ondo swap errors

​Wallet authorization errors

​Wallet connection errors

​OAuth errors

​KYC token errors

​Thrown errors

​Reading an API error code

​Next steps

Allowlist a wallet

Package overview

Wallet errors

Superstate swap errors

Token sale errors

Allowance resets

Ondo swap errors

Wallet authorization errors

Wallet connection errors

OAuth errors

KYC token errors

Thrown errors

Reading an API error code

Next steps