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. For signed POST /v2/request calls, “the same request” means the same signed JSON body. A retry may use fresh encryption, but it must not change clientTimestampMs, recvWindowMs, nonce, business fields, delegated-session proof, or signature. A request has unknown completion when the client gets no HTTP response or cannot finish reading the response body: retry the exact signed body while its replay window remains valid, or check committed identifiers such as requestIndex or order hash.

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. Duplicate keys, malformed JSON, wrong field types, `null` replay fields, negative replay fields, or out-of-range replay fields also return this code.	No	Fix the request contents, then sign and encrypt it again.
`ReplayFieldMissing`	`400`	The submitted signed request is missing `clientTimestampMs` or `recvWindowMs`.	No	Fetch operator time from `/v2/time`, add both replay-window fields, then sign and encrypt the request again.
`ReplayWindowZero`	`400`	`recvWindowMs` is `0`.	No	Use a positive receive window. Client helpers default to `5000`.
`ReplayWindowTooLarge`	`400`	`recvWindowMs` is greater than `60000`.	No	Use a receive window no larger than `60000` milliseconds.
`ReplayTimestampOverflow`	`400`	The replay-window expiry cannot be represented safely.	No	Use a valid operator-time timestamp and receive window.
`SignedRequestAuthenticationFailed`	`401`	The EIP-712 signature, signed request type, or delegated-session proof does not authorize the submitted request.	No	Sign the current request type, including `clientTimestampMs` and `recvWindowMs`, and use a valid delegated-session proof when one is present.
`Forbidden`	`403`	Trusted trader deny-list state rejected the delegated-session signer.	No	Fix the delegated-session authorization state before trying again.
`NonceCollision`	`409`	The operator has already retained a different signed request for the same trader, request family, and nonce.	No	Treat the request as a different intent and create a new signed request with a fresh nonce.
`NoChangesRequested`	`409`	A profile-update request was proven to be a no-op before request indexing.	No	Do not retry the same signed body. No request was indexed, and there is no receipt or `requestIndex`.
`ReplayTimestampExpired`	`412`	The signed replay window has expired.	No	Create a new signed request only if the trader is intentionally submitting a new intent.
`ReplayTimestampTooFarInFuture`	`412`	`clientTimestampMs` is at least `1000ms` ahead of operator time.	No	Fetch a fresh time snapshot from the same operator, then sign a new request.
`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	For a signed request that may have reached the operator, retry the exact signed body while its replay window remains valid or check committed identifiers. Otherwise wait for readiness before signing a new request.
`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.	No automatic retry	Slow down before submitting another request. Do not re-sign and resend automatically.
`InternalServerError`	`500`	An internal server fault prevented a final answer.	Only while valid or after checking the result	Treat signed-request completion as unknown. Retry the exact signed body while its replay window remains valid, or check committed identifiers before signing a new intent.
`TrustedTimeUnavailable`	`503`	The operator cannot prove trusted replay-validation time.	Sometimes	Wait for operator readiness before signing or retrying. Do not substitute local clock time.
`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 as `null` unless `error_reason` is `SafetyFailure` or another safety-specific response names a safety code.
`message`	string	Human-readable detail for logs and debugging. Useful context, but `error_reason` is the field to branch on in code.

Ordinary replay and request-shape errors serialize safety_failure as null:

{
  "error_reason": "ReplayTimestampExpired",
  "safety_failure": null,
  "message": "signed request replay window has expired"
}

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