Errors and edge cases

The SDK draws a line between two kinds of failure.

Flow-level failures are expected outcomes. The on-chain flows (passage.superstate.execute, passage.superstate.authorizeWallet, passage.tokenSale.execute, passage.ondo.prepareBuy, passage.ondo.prepareSell, passage.ondo.executeSwap, passage.centrifuge.buy, passage.centrifuge.prepareBuy, passage.centrifuge.sell, passage.centrifuge.prepareSell, passage.centrifuge.placeRequest, passage.centrifuge.claim), passage.wallets.connect, and passage.auth.signInWithWallet 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 passage.superstate.execute(swapParams);

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’s native token cannot pay the gas plus the transaction’s `value`. A short ERC-20 balance does not produce this.	Tell the user what is short. Retrying without a top-up will fail again.
`contract_reverted`	The contract rejected the transaction when the wallet simulated it or estimated its gas, so the wallet did not send it. Carries a `reason`: the contract’s `require` string, panic description, custom error name or selector, or `null` when the revert carried no data.	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.
`disconnected`	The wallet is no longer connected, or the user switched to an account other than the wallet’s `address`. Nothing was sent.	Do not retry through the same wallet: it fails the same way. Ask the user to reconnect or choose another wallet.
`unknown`	Unclassified. Carries the original `cause`.	Show a generic error and log `cause`.

The SDK classifies whatever your EvmWallet throws into a WalletError inside each flow, so you never classify one yourself. WalletError is exported from @passage-cl/react/universal. An exhaustive switch over it needs a disconnected case since v0.15.1.

Disconnected wallets

When an EvmWallet method cannot act because the wallet is gone, throw WalletDisconnectedError from @passage-cl/react/universal. Its constructor takes an optional message and an optional { cause }, such as new WalletDisconnectedError("The account changed.", { cause: error }). On viem or wagmi you can let the library’s own error propagate instead. The SDK reports disconnected when any error in the cause chain is one of these:

an object with the EIP-1193 code 4100, such as viem’s UnauthorizedProviderError or a provider’s plain ProviderRpcError
wagmi’s ConnectorNotConnectedError, matched by its name or its message, because the SDK does not depend on wagmi
a WalletDisconnectedError, matched by its name, so one thrown by a second copy of the SDK still counts

A rejected prompt wins: if the chain also holds a UserRejectedRequestError, or any object with the EIP-1193 code 4001, the result is user_rejected. Since v0.17.0 the code counts on its own, so a signer that calls the provider itself and rethrows its plain ProviderRpcError reports user_rejected rather than unknown. The SDK’s checkouts and claim dialog word a disconnected cause as “Your wallet disconnected - reconnect or choose another.” A checkout also notices on its own when you stop supplying the wallet the user confirmed: once no order is in flight, it reopens the wallet step with that message. A checkout that skipped its wallet step for preselected (every provider but Superstate, which keeps it) shows the message only when a send fails. A transaction that mined and then reverted is not a WalletError. Most flows report it as a step of their own, such as approval-reverted, swap-reverted or the Centrifuge claim’s reverted. superstate.authorizeWallet reports none: it re-checks the allow-list on-chain and ends as not-authorized unless the wallet is allow-listed. Since v0.15.0, contract_reverted also covers calldata that the backend built and your wallet sends with broadcastRawTx (Ondo swaps, Centrifuge requests and claims, the Superstate allow-list transaction). Before, a revert at gas estimation of those transactions was unknown.

Sent but not confirmed

A swap or a request that the wallet sent but whose receipt wait then failed has its own step, with the transaction hash: swap-unconfirmed (Superstate and Ondo), broadcast-unconfirmed (Superstate wallet authorization), request-unconfirmed (Centrifuge deposits and redemptions) and unconfirmed (Centrifuge claims). The transaction may still mine, so sending it again can fill the order twice. Look up txHash before you offer a retry. The SDK’s own checkouts disable the place-order button until the user leaves the step, and the SDK’s claim dialog offers no retry. The plain swap, broadcast and request steps mean the wallet never sent the transaction, so retrying is safe. An ERC-20 approval has no unconfirmed step: approve() sets the allowance rather than adding to it, so a failed receipt wait is reported as approval, and sending it again cannot approve twice.

Superstate swap errors

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

`step`	What happened
`status-check`	Reading the swap contract’s status failed.
`swap-paused`	The swap contract has suspended swapping and may resume. Ask the user to try again shortly.
`swap-stopped`	The swap contract is permanently halted. The swap has closed.
`allowance-check`	Reading the current ERC-20 allowance failed.
`approval`	The ERC-20 approval did not complete: the user declined it, or its receipt wait failed. A failed reset to zero lands here too. Carries a `WalletError` cause.
`approval-reverted`	The approval transaction, or the reset before it, reverted on-chain.
`swap`	The wallet never sent the swap transaction, so swapping again is safe. Carries a `WalletError` cause.
`swap-unconfirmed`	The swap was sent but its receipt wait failed. Carries `txHash` and a `WalletError` cause. It may still mine, so look up `txHash` before swapping again.
`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

passage.tokenSale.execute returns TokenSaleExecutionError.

`step`	What happened
`unsupported-chain`	The offer names no funding contract on the requested chain. Returned before the wallet is asked for anything.
`unsupported-asset`	The offer does not accept `inputAsset` on that chain. Returned before the wallet is asked for anything.
`unknown-option`	The offer has no option with that `optionId`. Returned before the wallet is asked for anything.
`allowance-check`	Reading the current ERC-20 allowance failed.
`allowance-reset`	The user did not sign the reset to zero, or its receipt wait failed. Carries a `WalletError` cause.
`allowance-reset-reverted`	The reset transaction reverted on-chain.
`approval`	The ERC-20 approval did not complete: the user declined it, or its receipt wait failed. 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 and retry with approval: { type: "mined", txHash: approvalTxHash }, which records the participation against that approval without prompting the wallet again.

Allowance resets

Every flow that approves an ERC-20 resets a non-zero allowance 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. The progress phases resetting-allowance and confirming-allowance-reset tell you when it happens. Only the token sale reports a failed reset as its own step, allowance-reset or allowance-reset-reverted. The other flows report it as approval or approval-reverted. A token sale also approves on every new participation, even when the current allowance already covers the amount.

Ondo swap errors

Placing an Ondo order is two calls, so it has two error types. passage.ondo.prepareBuy and passage.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 ERC-20 approval did not complete: the user declined it, or its receipt wait failed. A failed reset to zero lands here too. Carries a `WalletError` cause.
`approval-reverted`	The approval transaction, or the reset before it, 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-refused`	The API declined to build the order for a reason the user can act on. Carries a `reason` of type `OndoSwapRefusal`. Its one value is `requirements-not-met` (API code `requirements_not_met`): the user has not completed the requirements of the option that `offerOptionId` names.
`build-transaction`	Building the transaction failed for any other reason. A wallet that the API’s screening blocks has no error code yet, so it lands here, as does the 403 a wallet session gets when it builds for another wallet or chain.

Since v0.17.0, an exhaustive switch over OndoSwapPreparationError needs a build-refused case. Before, a requirements_not_met refusal was build-transaction. The SDK’s Ondo checkouts word it as “Complete the requirements for this offer before placing an order.” passage.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 wallet never sent the swap transaction, so placing the order again is safe. Carries a `WalletError` cause.
`swap-unconfirmed`	The swap was sent but its receipt wait failed. Carries `txHash` and a `WalletError` cause. It may still mine, so placing the order again can fill it twice. Look up `txHash` first.
`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.

Closed markets

passage.ondo.getQuote throws an HttpError when the market is closed or paused, as it does for any refused request. The API answers that case with a 409 and the code not_tradable, and isOndoNotTradableError(error) from @passage-cl/react/universal recognizes it. Tell the user to come back when the market opens rather than offering a retry.

import { isOndoNotTradableError } from "@passage-cl/react/universal";

async function loadQuote() {
  try {
    return await passage.ondo.getQuote(quoteParams);
  } catch (error) {
    if (isOndoNotTradableError(error)) {
      return showMarketClosed();
    }
    throw error;
  }
}

The Ondo hooks report the same case as the reason not-tradable (OndoLoadErrorReason). While the user is still on the step the flow opened on, both Ondo checkouts replace the flow with a “Trading is closed right now” screen until the market opens. Past that step, the amount step shows the block instead, so a closed market never takes an order dialog off the screen. The review step does not read the trading status: an order there can still be placed while its quote is valid.

Centrifuge errors

Centrifuge is @alpha, outside the compatibility contract. Its error types can still change in a minor release.

Preparing a request

passage.centrifuge.prepareBuy returns CentrifugeBuyPreparationError for a deposit, and passage.centrifuge.prepareSell returns CentrifugeSellPreparationError for a redemption. Both have the steps of OndoSwapPreparationError above, with more reasons on build-refused. unsupported-chain means the offer’s vaultContracts names no proxy on that chain. A redemption approves the vault’s share token, not the funding token, so its approval and approval-reverted steps are about the share token.

`step`	What happened
`build-refused`	The API declined to build the request for a reason the user can act on. Carries a `reason` of type `CentrifugeRequestRefusal`, from the table below.

`reason`	API error code	What it means
`requirements-not-met`	`requirements_not_met`	The user has not completed the requirements, such as KYC, of the option that the deposit’s `offerOptionId` names. Only deposits get it, because a redemption names no option.
`insufficient-balance`	`insufficient_balance`	The wallet holds less than the amount.
`direction-paused`	`deposit_paused`, `redeem_paused`	The vault proxy has paused this direction. It can resume, so ask the user to try again later.
`direction-stopped`	`deposit_stopped`, `redeem_stopped`	The vault proxy has stopped this direction for good.
`vault-refused`	`vault_refused_request`	Centrifuge itself would refuse the request. Try a different amount, or try again later.
`no-proxy-on-chain`	`no_proxy_on_chain`	The offer has no vault proxy on this chain.

An insufficient_allowance code is insufficient-allowance, as for Ondo. Any other failed build is build-transaction. A wallet that the API’s screening blocks has no error code yet, so it is build-transaction too, as is the 403 a wallet session gets when it builds for another wallet or chain.

Placing a request

passage.centrifuge.placeRequest broadcasts a built deposit or redemption and returns CentrifugeBuyPlacementError. passage.centrifuge.buy runs both halves of a deposit and returns CentrifugeBuyError, which is either type. passage.centrifuge.sell does the same for a redemption and returns CentrifugeSellError.

`step`	What happened
`request-expired`	The built request is stale, so the SDK did not send it. Either its deadline has passed, or the vault proxy refused its signature with an `Expired` or `Unauthorized` revert when the wallet simulated it. Another request or claim in the same direction between the build and the broadcast moves the wallet’s nonce, which causes `Unauthorized`. Either way, build a fresh request before you place again: passing the same one to `placeRequest` is refused the same way. `passage.centrifuge.buy` and `sell` build a fresh one on every call. The SDK’s deposit checkout rebuilds the request on its own, and its redemption checkout builds a fresh one when the user places again. Before v0.15.0, a refused signature arrived as `request` with an `unknown` cause.
`request`	The wallet never sent the request, so placing it again is safe. Carries a `WalletError` cause.
`request-unconfirmed`	The request was sent but its receipt wait failed. Carries `txHash` and a `WalletError` cause. It may still mine, so placing again can queue a second deposit or redemption.
`request-reverted`	The request transaction reverted on-chain.

The deposit checkout

Since v0.15.1, the SDK’s deposit checkout approves and builds the request when the user confirms the amount, so the review step can show the request’s fee. A CentrifugeBuyPreparationError therefore shows on the amount step, and the review step only places. If you render your own UI over useCentrifugeBuyCheckoutViewModel, its review is a CentrifugeBuyReviewUiState, which adds two arms to the shared review state:

{ type: "loading" } while there is no request to show, such as while an expired one is rebuilt.
{ type: "error", reason } when there is no request to place and building one is the user’s call. The reason is a CentrifugeBuyReviewErrorReason: build-failed (building the request failed) or expired (the request passed its deadline after the step’s one automatic rebuild, or arrived already past it). Send { type: "ON_RETRY" } to build again. The approval has already mined, so a retry asks for no signature.

A redemption still approves and builds when the user places it, so the redemption checkout has neither arm.

Claiming

passage.centrifuge.claim returns CentrifugeClaimError. It takes the vault’s share token symbol, asks the API to build the claim (passage.centrifuge.buildClaimTransaction), and has the wallet broadcast it. No approval comes first, and no amount is sent: the claim collects everything the wallet has claimable. The progress phases are building-transaction, awaiting-wallet and confirming.

`step`	What happened
`nothing-to-claim`	The API found nothing claimable, so the wallet was already paid. Do not retry, because a retry gets the same refusal.
`build-refused`	The API declined to build the claim. Carries a `reason` of type `CentrifugeClaimRefusal`: `vault-refused` (the vault proxy refused the claim; one retry can help) or `no-proxy-on-chain` (the offer has no vault proxy on this chain; no retry helps).
`build-transaction`	Building the claim failed for any other reason, such as the network, a server error, or the 403 a wallet session gets when it claims for another wallet or chain.
`claim-expired`	The built claim is stale, so the SDK did not send it. Either its deadline has passed, or the vault proxy refused its signature with an `Expired` or `Unauthorized` revert when the wallet simulated it. Claiming again builds a fresh one.
`broadcast`	The wallet did not send the claim, for any other reason. Carries a `WalletError` cause.
`unconfirmed`	The claim was sent but its receipt wait failed. Carries `txHash` and a `WalletError` cause. It may still mine, so look up `txHash` before claiming again.
`reverted`	The claim transaction reverted on-chain.

The SDK’s claim dialog offers Try again for vault-refused once, and never for nothing-to-claim, no-proxy-on-chain or unconfirmed. Every retry builds the claim again.

v0.15.0 moved the claim to the API. The SDK used to encode the claim and send it directly. passage.centrifuge.claim now requires symbol. The confirm step is gone: a claim that was sent but did not confirm is unconfirmed, and one that mined and reverted is reverted.

Unavailable checkouts

When a checkout cannot take an order at all, the SDK’s checkout replaces the flow with a “not available” screen instead of a failed step, and its god viewmodel’s state is { type: "error", reason }. For Ondo, Centrifuge and the token sale, the reason is a CheckoutBlockedReason<T>: unsupported-chain, unknown-option, or the provider’s own T. OndoCheckoutErrorReason adds not-tradable, CentrifugeCheckoutErrorReason adds not-orderable, and TokenSaleCheckoutErrorReason adds no-price and no-payable-asset. Superstate’s reason is a SuperstateSwapLoadErrorReason: unsupported-chain or load-failed. unknown-option applies to Ondo and Centrifuge since v0.15.0, because an Ondo order and a Centrifuge deposit send their option’s id. Since v0.16.0, optionId is required on every checkout and the SDK never picks an option, so unknown-option has one cause: optionId names no option the offer shows. The checkout blocks at mount, before any request. An offer with no options always blocks. A Superstate swap and a Centrifuge redemption ignore optionId and never block on it. An exhaustive switch on OndoCheckoutErrorReason or CentrifugeCheckoutErrorReason needs a case for it. See Building the Checkout flow. A wallet session can also hold a checkout back, without an error state. CheckoutContainer runs Ondo and Centrifuge checkouts through a session check first. On a wallet session, the user sees “Sign in to continue” when the option has any requirement, or “Connect your wallet” when wallets.external is not the session’s wallet. These cards have no button, so render your own next step.

Wallet authorization errors

passage.superstate.authorizeWallet returns WalletAuthorizationError. Like a swap, it splits a failed allow-list transaction into broadcast (never sent, safe to retry) and broadcast-unconfirmed (sent, carries txHash; look it up before authorizing again). See Superstate Swap for the full table and the progress phases.

Wallet connection errors

passage.wallets.connect returns { type: "error", error } with a ConnectWalletFlowError, which carries a code and a retryable flag. It returns { type: "cancelled" } when its isCancelled callback abandoned the attempt. The useConnectWallet hook surfaces the same failure as a ConnectWalletError, which adds display copy in message. Respect retryable when deciding whether to offer a retry button.

`code`	Meaning
`not_authenticated`	No CoinList user: the user is signed out or on a wallet session. Send the user through OAuth first. Not retryable.
`user_rejected`	The user declined the signature request.
`wallet_not_whitelisted`	The wallet is not allowlisted for this offer. Not retryable. See Superstate Swap.
`max_wallets_reached`	The user has already connected the maximum number of wallets for the offer option. Not retryable.
`unknown`	Unclassified.

passage.wallets.connect has no disconnected code. Only a rejected signature maps to user_rejected, so a wallet that disconnected while signing the challenge reports unknown.

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 redirect came back with an `error` parameter, usually because 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, or no value was stored. 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: your `postOAuthComplete` resolved `false` or rejected. `useCompleteOAuth` also reports it when `passage.init()` rejects after the exchange, or your `onSuccess` throws.

passage.auth.signInWithWallet and signIn from useWalletSignIn resolve with a WalletSignInResult. Only a missing walletSignIn prop rejects: see Thrown errors.

`type`	Meaning
`signed-in`	The session exists, and the auth state is logged in with the wallet.
`canceled`	The user rejected the signature. Not an error state.
`failed`	Carries a `step`, below, and no `WalletError`: the SDK logs the cause. The user can try again.

`step`	What happened
`challenge`	Your `challenge` call threw, or `walletSignIn.connection` is not `connected` at the signing wallet’s address, in which case nothing reached your backend.
`signature`	The wallet failed for a reason other than the user, or the wallet changed or the user logged out while it asked for the signature.
`complete`	Your `complete` call threw, reading the new session failed, your backend does not serve a wallet session for this wallet, or the user logged out while your backend stored the session. A failure here can still leave a session on your backend for the wallet that signed, and the next load picks it up.

On your backend, auth.walletChallenge throws an HttpError with a 403 when wallet sign-in is not enabled for your OAuth client, or a 422 for an invalid address or a redirectUri that is not one of the client’s. auth.completeWalletSignIn throws an HttpError with a 400 when the signature does not match an active challenge or wallet sign-in is not enabled, and WritableSessionStoreRequiredError without setSession. The SDK never retries auth.completeWalletSignIn, because a challenge is single-use.

Hook load errors

Data hooks report a failed read as an ERROR state with a reason: not-authenticated or generic-error. No retry helps not-authenticated until the user signs in. Offer a retry for generic-error. A wallet session is not a CoinList user, so useOffers, useOfferDetails, useRequirements, useOptionAddresses, useKycToken, and useCoinListTokenSaleParticipations report not-authenticated on one, and no retry helps. Read offers on your server and pass them as data, and use useOfferRequirements to read an offer’s requirements without their statuses. The ERC-20 balance hooks, useSwapQuote, useSwapOutputToken, useOfferRequirements, the Ondo and Centrifuge hooks, and useCoinListTokenSaleParticipations use the shared LoadErrorReason. On these, not-authenticated covers both a NotAuthenticatedError and an HTTP 401, including the 401 from CoinList’s JSON-RPC proxy that on-chain reads go through, so an expired session reads the same whichever request noticed it. useOffers, useOfferDetails, useRequirements and useOptionAddresses declare their own reason types with the same two values. On these, not-authenticated means only a NotAuthenticatedError (no CoinList user), and an HTTP 401 reports generic-error. The Ondo hooks widen it to OndoLoadErrorReason, which adds not-tradable for a closed market. useKycToken reports its own KycTokenErrorReason, with the same two values: not-authenticated when there is no CoinList user, or generic-error for everything else.

Thrown errors

Each error class has exactly one entry point. Import the universal ones (NotAuthenticatedError, HttpError, ValidationError, InvariantError, MathError, NotImplementedError, plus apiErrorCode and isOndoNotTradableError) from @passage-cl/react/universal. The main entry point does not re-export them. Because the package is ESM-only, every entry point shares one copy of each class, so error instanceof HttpError holds whichever entry point the failing call came from.

Error	Entry point	When
`NotAuthenticatedError`	`/universal`	An API-backed method was called without the session it needs. In the browser, the auth state’s `type` is not `'logged-in'`. On a `PassageServer`, the session store has no session, or the session was rejected. On either, a wallet session called a method that needs a CoinList user: see Which session a method needs. When the server could not find out, because CoinList’s token endpoint or the network failed, the method throws that underlying error instead.
`HttpError`	`/universal`	The API refused a request. Carries the `response`; read the body’s error code with `apiErrorCode(error)`. `error.requestId` matches the SDK’s `HTTP` log lines for the same request.
`ValidationError`	`/universal`	A value the SDK cannot accept. Examples: an Ondo quote sized by both `tokenAmount` and `notionalValue`, or by neither; an unrecognized chain string; a response from the backend in a shape the SDK does not understand. `createPassageClient` and `createPassageServer` also throw it when `Config.baseUrl` or `Config.tokensBaseUrl` is an empty or whitespace-only string, with the message `Config.baseUrl is empty. Omit it to use the default, or set a URL.` In React, that throw comes from rendering `PassageProvider`. Omit the field to use the production default.
`InvariantError`	`/universal`	The SDK computed something impossible, such as a value outside uint256 after its own arithmetic. Report it as an SDK bug.
`MathError`	`/universal`	An arithmetic operation had no answer, such as a division by zero or a result out of range, although every operand was well-formed.
`NotImplementedError`	`/universal`	Reserved for a code path that is not implemented yet. No public method throws it in this release.
`PassageClientInitializationError`	`@passage-cl/react`	`usePassage()` was called outside `PassageProvider`. Its message is `usePassage() must be used within PassageProvider. Wrap your app with <PassageProvider config={...}>.`
`WalletSignInConfigRequiredError`	`@passage-cl/react`	`passage.auth.signInWithWallet`, or `signIn` from `useWalletSignIn`, was called without `PassageProvider`’s `walletSignIn` prop. Nothing else supplies those calls, so a client from `createPassageClient` alone always rejects with it. A retry cannot fix it.
`WritableSessionStoreRequiredError`	`/server`	`auth.completeOAuth`, `auth.completeWalletSignIn`, or `auth.logout` was called on a `PassageServer` with a read-only session store.

Which session a method needs

A wallet session is not a CoinList user, so NotAuthenticatedError depends on the method.

Session	Methods
A CoinList user or a wallet session	`ondo.getTradingStatus`, `ondo.getQuote`, `ondo.buildBuyTransaction`, `ondo.buildSellTransaction`, `centrifuge.getVaultStatus`, `centrifuge.buildBuyTransaction`, `centrifuge.buildRedeemTransaction`, `centrifuge.buildClaimTransaction`, and `requirements.forOffer`
A CoinList user	`offers.`, `requirements.statuses`, `requirements.createKycToken`, `requirements.getPii`, `requirements.submitDocument`, `wallets.`, `tokenSale.list`, `tokenSale.listPage`, `tokenSale.get`, `tokenSale.createParticipation`, and `superstate.allowWallet`

wallets.connect is the exception in that row: it never throws, and on a wallet session it returns the not_authenticated code. A wallet session builds only for its own wallet and chain: the API answers any other with a 403, as an HttpError. On a PassageServer, offers.* and requirements.forOffer also take an app-level token from auth.clientCredentials(), and need no session with one. A CoinList user’s session takes precedence over that token, but a call on a wallet session sends the token. Without one, offers.* throws NotAuthenticatedError on a wallet session.

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 "@passage-cl/react/universal";

async function buildBuy() {
  try {
    return await passage.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

Disconnected wallets

Sent but not confirmed

Superstate swap errors

Token sale errors

Allowance resets

Ondo swap errors

Closed markets

Centrifuge errors

Preparing a request

Placing a request

The deposit checkout

Claiming

Unavailable checkouts

Wallet authorization errors

Wallet connection errors

OAuth errors

Hook load errors

Thrown errors

Which session a method needs

Reading an API error code

Next steps

Allowlist a wallet

Package overview

​Wallet errors

​Disconnected wallets

​Sent but not confirmed

​Superstate swap errors

​Token sale errors

​Allowance resets

​Ondo swap errors

​Closed markets

​Centrifuge errors

​Preparing a request

​Placing a request

​The deposit checkout

​Claiming

​Unavailable checkouts

​Wallet authorization errors

​Wallet connection errors

​OAuth errors

​Wallet sign-in errors

​Hook load errors

​Thrown errors

​Which session a method needs

​Reading an API error code

​Next steps

Allowlist a wallet

Package overview

Wallet errors

Disconnected wallets

Sent but not confirmed

Superstate swap errors

Token sale errors

Allowance resets

Ondo swap errors

Closed markets

Centrifuge errors

Preparing a request

Placing a request

The deposit checkout

Claiming

Unavailable checkouts

Wallet authorization errors

Wallet connection errors

OAuth errors

Wallet sign-in errors

Hook load errors

Thrown errors

Which session a method needs

Reading an API error code

Next steps