Errors
This page lists the error classes the SDK throws, the fields each carries, and the contract error names the SDK decodes into ContractRevertError. For the decision logic that goes with them, see Handle errors and reverts.
Every SDK error extends SomniaMarketsError, sets name to its class name, prefixes its message with @somnia-chain/markets-sdk: , and carries the underlying failure in cause when it wraps one.
Classes
All classes are exported from the root entry.
| Class | Fields | Meaning | Retrying the same call |
|---|---|---|---|
SomniaMarketsError | none | Base class. | depends on the subclass |
InvalidInputError | none | The call cannot proceed: unknown symbol or reference, unknown timeframe, a method used on the wrong market kind, an amount below one lot, a limit order without a price, a market order against an empty opposite side, a probability outside [0, 1], or a non-finite amount. Most cases are local validation. The empty-book market-order case follows a chain book read and depends on current liquidity. | fails again, except an empty-book market order may succeed after liquidity appears |
NotConfiguredError | what: string | The client lacks a URL or address the feature needs: wsRpcUrl, priceFeed, or an entry of addresses. Thrown at the first call that needs it, not at construction. The one exception is an empty indexerUrl, which the constructor rejects. | fails again |
SignerRequiredError | operation: string | An authenticated method was called without a privateKey, account, or walletClient. Authenticated methods include fetchBalance, fetchOpenOrders, fetchOrders, fetchMyTrades, fetchPositions, watchOrders, watchMyTrades, exchange.trader, and every write. | fails again |
IndexerError | operation: string | An indexer request did not complete: endpoint down, bad URL, HTTP error, GraphQL error, or the 30-second request timeout. Never means "no such row". | may succeed |
RpcError | operation: string | A JSON-RPC or WebSocket request did not complete: connection refused, 4-second request timeout, dropped subscription, unsupported method. The request never produced a chain answer. | may succeed |
ContractRevertError | errorName?, args?, reason?, data?, address?, functionName? | The chain rejected the call. Thrown on send-time rejection, pre-send simulation, a mined receipt with failed status, and eth_call reads. | fails again unless state changes |
Errors from code the SDK calls but does not own can surface unchanged. This includes a walletClient supplied by the app and the client returned by getViemClient(). Debug sink failures are different: the SDK contains them so diagnostic code cannot break an operation.
An InvariantError exists for contradictions in the SDK's own reasoning. It is not exported and indicates an SDK defect.
ContractRevertError fields
| Field | Type | Present when |
|---|---|---|
errorName | string | The revert data matched a custom error in contractErrorsAbi. |
args | readonly unknown[] | errorName is set. Positional decoded arguments. |
reason | string | The revert carried a require or revert string. |
data | string | The node returned revert data. |
address | string | The reverting contract is known. |
functionName | string | The called function is known. |
A mined transaction with status: "reverted" carries no revert data. The SDK replays the call as eth_call at the receipt's block to recover errorName or reason. When the replay yields nothing, the error is still a ContractRevertError and its message ends with (no revert data recoverable).
decodeRevert(caught) is exported for callers who send transactions themselves. It walks the cause chain, decodes the first revert data it finds against contractErrorsAbi, and always returns a ContractRevertError. It does not check that the input is a revert: a transport error passed to it returns a ContractRevertError without errorName.
Absence versus failure
| Outcome | Indexer point read (get*) | Indexer list read (list*) | Chain read | Live-store read |
|---|---|---|---|---|
| Row exists | the row | the rows | the value | the value |
| No such row | null | [] | throws ContractRevertError or returns the contract's empty value | [], null, or an empty book |
| Request failed | throws IndexerError | throws IndexerError | throws RpcError or ContractRevertError | not applicable |
Contract error names
contractErrorsAbi, exported from the root entry, is the generated ABI of every custom error the protocol contracts declare. ContractRevertError.errorName is one of its names. The names the exchange API and the trader raise most often:
| Area | Error names |
|---|---|
| Order validation | InvalidPrice, InvalidQuantity, PriceNotAlignedToTickSize, QuantityNotAlignedToLotSize, QuantityBelowMinimum, PriceOutOfBounds, PriceTooLarge, TooManyRestingOrders |
| Market state | TradingNotActive, UseBinaryPlacement, MarketRestricted, MarketNotSettled, NotFinalized, StaleMarketId |
| Order lifecycle | OrderDoesNotExist, IncorrectSender (a cancel of an order the caller does not own, including an order already cancelled), OrderAlreadyExpired, ExpiredOrderMustBeCancelled, NotExpired, OrderExpiryBeyondMarket |
| Time in force | PostOnlyWouldCross, FillOrKillNotFillable, ImmediateOrCancelNoFill, SelfMatchCancelTaker |
| Amend and batch | AmendOldOrderGone, AmendReplacementRejected, EmptyOrderBatch, BatchTooLarge, LengthMismatch |
| Funds | InsufficientBalance, InsufficientVaultBalance, ExceedsWithdrawableBalance, ERC20InsufficientAllowance, ERC20InsufficientBalance, InvalidMsgValue, NativeAmountMismatch |
| Builder fees | BuilderNotApproved, BuilderFeeExceedsApproval, BuilderFeeExceedsCap, InvalidBuilder |
| Binary settlement | NothingToClaim, AlreadyClaimed, NothingOwed, AlreadyFinalized, OracleNotAnswered, QuestionNotFinal |
| Perps | NoOpenPosition, InsufficientMargin, InsufficientMarginForOrder, InsufficientMarginAfterWithdrawal, MaxPositionSizeExceeded, OpenInterestCapExceeded, InvalidLeverage, MarkPriceUnavailable, OraclePriceStale, NotLiquidatable, PerpPoolNotRegistered |
| Stop orders | InvalidTriggerPrice, LimitPriceIncompatibleWithTrigger, InsufficientSomiPayment, TriggerTooCloseToEma, RefundFailed |
| Operators and venues | OperatorDisabled, OperatorNotActive, UnknownOperator, UnknownVenue, VenuePolicyDenied, InsufficientPermission, Unauthorized, NotOwner |
| Test collateral | FaucetCapExceeded |
The full list is longer and changes with the contracts. Read it from contractErrorsAbi in the installed version.