Errors & Messages

Every failure a Bazaar call can raise has a sentence a user can act on. The SDK ships one message for every custom error the five Bazaar contracts declare, explains the failures wallets raise before anything reaches the chain, and refuses bad inputs with errors that name the field. This page covers what can be thrown, how to turn it into text, and the few cases you still have to handle yourself.

The samples assume bz connected as in Connecting, user the wallet’s address and eth a market.

The Short Version

try {
  const call = await bz.trade.createOrder(eth.address, user, {
    orderType: OrderType.Market,
    isLong: true,
    size: parseUnits18("1"),
    maxSlippageBp: 50n,
  });
  const sim = await bz.simulate(call);
  if (!sim.ok) throw sim.error!; // a DecodedError
  await bz.waitForReceipt(await bz.send(window.ethereum, call));
} catch (e) {
  show(errorMessage(e)); // one sentence, whatever failed
}

errorMessage(e) takes anything a call threw (or a simulation’s error) and returns one sentence. It never returns a raw URL or a stack trace. Use it as the default, and add the cases in A Complete Handler for the errors it does not explain.

What Can Be Thrown

errorMessage

errorMessage(e) checks, in order:

1. A DecodedError: its message.
2. An InputError: its message (which starts with the field: "amount: The minimum deposit is 5 USDC.").
3. A NoFreshPriceError: “No fresh price is available for this market right now, and this action needs one. Try again in a moment.”
4. An error carrying a decoded DecodedError (a CallError): that error’s message.
5. A wallet-side failure (walletErrorMessage, below).
6. An RPC error carrying revert data: the decoded revert’s message; with empty revert data, “The call reverted without a reason (often out of gas).”
7. Anything else: “Something went wrong. Please try again.”

Step 7 catches more than it should: a SigningError or ClockSkewError (including “You declined the signature.”), a ConnectError, and a CallError without decoded data (a reverted receipt, a timeout) all come out as the generic sentence, although each carries a good message of its own. Handle them before calling errorMessage, as the handler below does.

Decoded Reverts

A simulation that fails returns a DecodedError:

const sim = await bz.simulate(await bz.trade.withdrawCollateral(eth.address, user, parseUnits18("1000000")));
if (sim.error) {
  sim.error.name; // e.g. "CollateralLib__InsufficientCollateral"
  sim.error.args; // { amount: 1000000000000000000000000n, available: 2500000000000000000000n }
  sim.error.message; // "You asked for $1,000,000.00, but only $2,500.00 is available."
  sim.error.hint; // the operator-facing hint, or ""
  sim.error.data; // the raw revert data
  sim.error.opensAt(); // for a "too early" error, when the call opens (unix seconds); else null
  String(sim.error); // "CollateralLib__InsufficientCollateral(amount=..., available=...)", for logs
}

decodeError(data) decodes any revert data:

User Messages

USER_MESSAGES holds one message for every custom error the five contracts declare (BazaarPair, and the libraries it links whose errors surface at its address, BazaarFactory, BazaarPairLens, BazaarPairTerminator and BazaarOracle): 187 errors, the Bazaar ones from BazaarPair__TradingHalted to Factory__ProposalNotFound and the OpenZeppelin ones the contracts inherit (SafeERC20FailedOperation, ECDSAInvalidSignature, ReentrancyGuardReentrantCall, the SafeCast overflows, …). The SDK’s test suite fails when an error in the ABIs has no message. Each says what happened and what to do, with the error’s arguments formatted: BAZAAR-precision amounts as dollars, prices with their decimals, basis points as percents, times as dates with a relative hint.

userMessage("OrderManagementLib__TooManyActiveLimitOrders");
// "You have the maximum of 32 open limit and stop-limit orders on this market. Cancel some first."
userMessage("MetaTx__InvalidNonce", { expected: 7n }); // arguments are formatted into the text
Object.keys(USER_MESSAGES).length; // one per custom error the five contracts declare

userMessage(name, args?) returns the message for an error name (the name itself when unknown). Bazaar.connect registers the messages with the decoder, so DecodedError.message returns them; installUserMessages() does the same explicitly, for code that decodes without connecting (it is idempotent).

The formatters the messages use are exported in the format namespace, for showing amounts the same way: formatUsd (“$1,234.56”; amounts under a cent keep six decimals), formatPrice (“$3,012.5”), formatAmount (“1.25”), formatBp (250 to “2.5%”), formatEth (“0.0001 ETH”), formatDuration (“12 min”) and formatTime (“2026-11-08 14:00 UTC (in 3 h)”).

Wallet Errors

walletErrorMessage(e) explains failures the wallet raised rather than the contract, and returns null for anything else. It walks cause chains, so it reads errors from viem, ethers and raw providers.

try {
  await bz.send(window.ethereum, await bz.trade.cancelOrders(eth.address, user, [1n]));
} catch (e) {
  const wallet = walletErrorMessage(e); // null unless the wallet itself refused
  if (wallet) show(wallet); // "You rejected the request in your wallet."
}

InputError

Builders check their arguments before reading the chain or asking for a signature, and throw InputError with field, the argument at fault ("amount", "limitPrice", "orderIds", "pair", …). The message is prefixed with the field; strip it to show the sentence next to that input:

try {
  await bz.trade.depositCollateral(eth.address, user, parseUnits18("2"));
} catch (e) {
  if (e instanceof InputError) {
    e.field; // "amount": put the message next to that input
    e.message; // "amount: The minimum deposit is 5 USDC."
    e.message.slice(e.field.length + 2); // "The minimum deposit is 5 USDC."
  }
}

The order form on Placing Orders does this on every keystroke with buildOrderSpec, which throws the same errors without any read.

CallError and ClockSkewError

CallError (see Sending Transactions) has message, decoded (the DecodedError when the wallet’s error carried revert data) and cause.

ClockSkewError has chainTime (the latest block’s timestamp as the RPC reported it) and localTime (the device’s clock), both unix seconds, and a message telling the user to set the device’s clock to update automatically or to connect through another RPC.

Errors the SDK Does Not Name

A few reverts come from contracts outside the five ABIs:

• Pyth’s StalePrice() (Unknown(0x19abf40e)): a direct call’s price update aged past the 3-second window before the transaction landed. The most common failure of a slow direct send. Rebuild the call and send it again (Sending Transactions).
• USDC’s require messages (Error): “ERC20: transfer amount exceeds allowance” or “… balance”. Check funding first with usdcFunding (Collateral).
• The example trading account’s BazaarTradingAccount__NotOwner (an Unknown(...) selector): the sender is not the account’s owner (Smart Accounts & Batching).

A Complete Handler

/** Errors the SDK's ABIs do not declare, by the name decodeError gives them. */
const EXTRA_MESSAGES: Record<string, string> = {
  // Pyth's StalePrice(): the price update aged past the pair's 3 s window before the call landed.
  "Unknown(0x19abf40e)": "The price moved on before your transaction landed. Try again.",
};

/** What to show for any error a Bazaar call can throw. */
function explain(e: unknown): string {
  // A decoded revert the SDK has no sentence for (e.g. Pyth's own errors).
  const decoded = e instanceof DecodedError ? e : e instanceof CallError ? e.decoded : null;
  if (decoded && EXTRA_MESSAGES[decoded.name]) return EXTRA_MESSAGES[decoded.name]!;
  // The builders' input errors: the sentence without its "field: " prefix.
  if (e instanceof InputError) return e.message.slice(e.field.length + 2);
  // Signing (declined, clock skew, a smart-account signature) and connection errors carry their own
  // sentence, which errorMessage does not pass through.
  if (e instanceof signing.SigningError || e instanceof ConnectError) {
    return walletErrorMessage(e) ?? e.message;
  }
  // A receipt that reverted carries no reason: say so plainly.
  if (e instanceof CallError && !e.decoded && /reverted$/.test(e.message)) {
    return "The transaction was reverted on chain. Nothing changed; check the market and try again.";
  }
  return errorMessage(e);
}

explain(decodeError("0x19abf40e")); // "The price moved on before your transaction landed. Try again."

Showing Errors in a UI

• Simulate before you ask for a signature, and show sim.error.message instead of opening the wallet. A user who never signs a doomed transaction never pays for one.
• Put input errors next to their field, using InputError.field, and keep the submit button disabled while there is one.
• Gate buttons on the market’s flags (marketOrdersDisabled, positionWithdrawalsFrozen, …, with reasons) rather than waiting for a revert (Markets).
• Show the sentence, log the detail. Show explain(e); log String(decoded) or e.cause for support.
• Treat a rejection as a choice, not an error. “You rejected the request in your wallet.” needs no red banner.
• Offer a retry where a retry helps: a stale price, an expired gasless signature (MetaTx__ExpiredDeadline), a nonce that moved (MetaTx__InvalidNonce). Rebuild or re-sign; do not resend the same call.
• Render on-chain strings as text, never as HTML (Security Notes).

Related Pages

• Sending Transactions: simulate, send, CallError.
• Previews: the same messages, before a call is even built.
• Gasless Trading & Relayers: the MetaTx__ errors and the relayer’s checks.