Error Reference - DerivaDEX Docs

DerivaDEX errors can appear in three places: the HTTP response to a private request, a failed WebSocket subscribe or unsubscribe message, or a rejection in the realtime account feeds.

Where errors appear

Use this table to identify the source of the error before looking up the code itself.

Error appears in	Where it appears	What it means
HTTP response	HTTP response from `POST /v2/request`	The request failed before the operator accepted it, or before the client received a final answer.
WebSocket control	`ACKNOWLEDGE.result.error`	A subscribe or unsubscribe command failed. The WebSocket connection itself can still be healthy.
Realtime rejection	`ORDER_UPDATE`, `STRATEGY_UPDATE`, or `TRADER_UPDATE` rejection fields	The connection stayed up, but a specific order, withdrawal, or trader-level action was rejected later in processing.

HTTP error codes

These are the public error_reason values returned by the private request endpoint, along with the right response for each one.

Error reason	Status	Meaning	Send the same request again?	What to do
`InvalidRequestPayload`	`400`	The request body could not be parsed as a valid DerivaDEX request. Missing replay-window fields, half-filled replay-window fields, or other malformed input also return this code.	No	Fix the request contents, then sign and encrypt it again.
`SignerNotFound`	`401`	Signature recovery succeeded, but the recovered signer is not a recognized trader.	No	Sign with the correct trader wallet or delegated session key.
`Forbidden`	`403`	The request was understood but denied by operator policy. This includes delegated-session expiry and ACL violations.	No	Fix the authorization state before trying again.
`KycNotFound`	`404`	Required KYC state is missing or expired.	No	Resolve KYC state before retrying.
`IllegalNonce`	`412`	Replay protection rejected the request nonce because it was stale, duplicated, or otherwise invalid for the current request window.	No	Build a fresh request with new replay fields instead of sending the same one again.
`NotAcceptingRequests`	`421`	The operator is temporarily unable to take this kind of request. This can happen during leader changes, readiness changes, or other short-lived request-path transitions.	Sometimes	Pause, check readiness, then retry a limited number of times.
`InvalidEncryption`	`422`	The operator could not decrypt the encrypted payload bytes.	No	Re-encrypt the exact signed payload with the current operator key.
`SafetyFailure`	`422`	Request validation rejected the order or account action because it broke a trading, balance, or withdrawal rule.	No	Fix the request or the account state before retrying.
`RateLimit`	`429`	The authenticated signer exceeded the current request quota.	Yes	Slow down, wait, and try again.
`InternalServerError`	`500`	An internal server fault prevented a final answer.	Only after checking the result	Check whether the request already took effect before sending it again.
`ServiceUnavailable`	`503`	A required dependency was not ready. Today this includes `MarketPriceNotAvailable`.	Sometimes	Wait briefly, then try again. If it keeps happening, check whether price data or another dependency is missing.

Error response format

Every HTTP error response uses the same three fields.

Field	Type	Meaning
`error_reason`	enum	The main error code. Read this first.
`safety_failure`	enum or `null`	Present only when `error_reason` is `SafetyFailure`.
`message`	string	Human-readable detail for logs and debugging. Useful context, but `error_reason` is the field to branch on in code.

Safety-failure codes

These safety_failure values appear only alongside 422 SafetyFailure, except for MarketPriceNotAvailable, which currently maps to 503 ServiceUnavailable.

Trader and strategy state

These codes mean the request referred to a trader or strategy state the operator could not use.

Variant	Meaning
`TraderNotFound`	Trader address was not found in verified state.
`NoStrategies`	The trader has no strategies.
`StrategyNotFound`	The specified strategy does not exist for the trader.
`OrderNotFound`	The referenced order hash was not found.
`InsuranceFundContributionNotFound`	The referenced insurance-fund contribution was not found.
`AccessDenied`	Trader access is denied.
`UnsupportedTraderUpdate`	The requested trader update type is not supported.

Order details and market rules

These codes mean the request itself broke a market rule before the order could move forward.

Variant	Meaning
`SignatureRecoveryMismatch`	EIP-712 signature recovery did not match the intended trader identity.
`OrderPriceNeg`	Order price was negative.
`OrderAmountZeroNeg`	Order amount was zero or negative.
`OrderAmountNotMultipleOfMinOrderSize`	Order amount was not a valid multiple of the minimum order size.
`OrderTypeIncompatibleWithPrice`	Order type and price fields were inconsistent.
`PriceNotMultipleOfTickSize`	Price was not a valid multiple of the market tick size.
`UnsupportedMarket`	The symbol is not a supported market.
`UnsupportedCurrency`	The request used an unsupported currency. Public trading flows require `USDC`.
`MaxOrderNotionalBreached`	Order notional exceeded the market maximum.
`MaxTakerPriceDeviationBreached`	The order would breach the taker price-deviation guard.
`TooManyOrders`	The strategy already has too many open orders for that market.
`CancelNoLiquidityForMarket`	There was no open liquidity to cancel for the requested symbol.

Margin, collateral, and withdrawal checks

These codes mean the request itself was well-formed, but the trader’s account did not meet a balance or solvency rule.

Variant	Meaning
`NotEnoughCollateral`	Collateral was below the required minimum for the requested action.
`OMFLessThanIMF`	The post-trade open margin fraction would fall below the initial margin requirement.
`MaxWithdrawAmountBreached`	The collateral withdrawal exceeded the allowed maximum.
`MaxDDXWithdrawAmountBreached`	The DDX withdrawal exceeded the allowed maximum.
`TooMuchCollateralToWithdrawDDX`	The requested DDX withdrawal would violate the collateral cap that applies after the withdrawal.
`MaxInsuranceFundWithdrawBreached`	The insurance-fund withdrawal exceeded the allowed maximum.
`WithdrawAmountZeroNeg`	Collateral withdrawal amount was zero or negative.
`WithdrawDDXAmountZeroNeg`	DDX withdrawal amount was zero or negative.
`WithdrawInsuranceFundZeroNeg`	Insurance-fund withdrawal amount was zero or negative.

Mark-price availability

This code means the operator did not have the required mark price yet. It does not mean the request itself was malformed.

Variant	Meaning
`MarketPriceNotAvailable`	Mark price was unavailable for the requested symbol. The current runtime returns this as `503 ServiceUnavailable`.

Rejections in realtime feeds

Rejections in realtime feeds do not use the HTTP error_reason fields. They appear inside the feed payload itself.

Rejection appears in	Where to read it	Meaning	Next lookup
Subscription control	`ACKNOWLEDGE.result.error`	A subscribe or unsubscribe command failed.	Realtime Channels
Order rejection	`ORDER_UPDATE.orderRejection` or `ORDER_UPDATE.cancelRejection`	An order, cancel, or modify action was rejected after the request was accepted.	Order and Account Event Reference
Strategy rejection	`STRATEGY_UPDATE.withdrawRejection`	A collateral or insurance-fund withdrawal action was rejected.	Order and Account Event Reference
Trader rejection	`TRADER_UPDATE.withdrawDDXRejection`	A trader-level DDX withdrawal action was rejected.	Order and Account Event Reference

​Where errors appear

​HTTP error codes

​Error response format

​Safety-failure codes

​Trader and strategy state

​Order details and market rules

​Margin, collateral, and withdrawal checks

​Mark-price availability

​Rejections in realtime feeds

​Related references