HTTP-level classes for request submission
| Error reason | Status | Meaning | Client action |
|---|---|---|---|
InvalidRequestPayload | 400 | Decrypted payload could not be parsed as a request, including missing or partially populated replay-window fields | Fix serialization or replay-window field pairing before retry |
InvalidRecvWindow | 400 | Receive-window value is invalid | Fix timing window before retry |
SignerNotFound | 401 | Recovered signer is not recognized | Use the correct trader wallet |
SessionUnauthorized | 401 | Delegated session payload failed policy checks | Rotate or repair session payload |
Forbidden | 403 | Request understood but refused by server policy | Stop and inspect access posture |
KycNotFound | 404 | Required KYC state is missing or expired | Resolve KYC state before retry |
IllegalNonce | 412 | Nonce conflicted with replay-window duplicate-state policy | Generate a fresh nonce and replay-window tuple that is not treated as duplicate |
ExpiredTimestamp | 412 | Request timestamp is too old | Rebuild request with current timestamp |
FutureTimestamp | 412 | Request timestamp is too far in the future | Correct client clock and rebuild request |
NotAcceptingRequests | 421 | Sequencing is not currently admitting the request path, including leader or readiness transitions and pending durable-commit cases | Pause writes, confirm readiness, then retry with bounds |
InvalidEncryption | 422 | Payload could not be decrypted | Re-encrypt with fresh key material |
SafetyFailure | 422 | Request violated execution or risk guards | Repair payload, then resign and re-encrypt |
RateLimit | 429 | Request quota exceeded | Back off and retry |
InternalServerError | 500 | Internal server fault | Retry cautiously after health checks |
ServiceUnavailable | 503 | Service unavailable, including missing mark-price state | Retry with jitter |
Use this page when
| If you need… | Use this page because… |
|---|---|
| the canonical public error lookup | it centralizes HTTP classes, safety failures, and realtime rejection surfaces |
| to distinguish retryable faults from payload or state defects | it pairs reason classes with client action |
| the broader runtime union rather than the narrower generated artifact view | this page already calls out spec omissions and current runtime authority |
Source-alignment note
This reference reflects the runtimeErrorReason mapping used by API code. The generated operator client-request OpenAPI artifact currently exposes a narrower ErrorReason enum and does not yet list every replay or session reason in this table. Treat this page as the canonical public lookup derived from runtime source until those artifacts converge.
Current generated-spec omissions:
InvalidRecvWindowExpiredTimestampFutureTimestampSessionUnauthorized
Replay-window note
The live sequencing contract is stricter than “always increase a global nonce by one” and also more nuanced than “any new nonce is fine.” Freshness is determined by the replay window plus duplicate-marker state. Missing or partially populated replay-window fields map toInvalidRequestPayload rather than to a standalone public error enum. Current regression coverage explicitly includes fresh lower-nonce CancelOrder and CancelAll requests that remain admissible when they are non-duplicate and still inside the valid receive window.
Recovery grouping
| Error family | Public recovery rule |
|---|---|
| malformed payload or schema failure | fail fast, repair payload, then rebuild |
| signer, session, or encryption failure | repair identity or cryptographic material before retry |
| replay-window or nonce failure | rebuild timestamp and nonce context instead of blindly resending |
| safety failure | fix product, price, amount, collateral, or strategy state before retry |
| rate-limit and service-availability failure | bounded retry with backoff, jitter, and health awareness |
Retry classes
| Retry class | Public reading |
|---|---|
| do not retry unchanged | malformed payloads, signer/session/encryption defects, and safety failures |
| retry only after rebuilding request context | replay-window, timestamp, and nonce failures |
| bounded retry is appropriate | rate limits, service unavailability, and leader/readiness transitions |
Error payload shape
| Field | Type | Notes |
|---|---|---|
error_reason | enum | Top-level error class returned by the API |
safety_failure | enum or null | Present when error_reason is SafetyFailure |
message | string | Human-readable error detail |
Safety failure variants
These variants are declared incore/common/src/types/primitives.rs.
| Variant | Meaning |
|---|---|
TraderNotFound | Trader address not found in verified state |
NotEnoughCollateral | Collateral below required minimum |
NoStrategies | Trader has no strategies |
StrategyNotFound | Strategy identifier not found for trader |
SignatureRecoveryMismatch | EIP-712 signer mismatch |
InsuranceFundContributionNotFound | Insurance-fund contribution not found |
MaxOrderNotionalBreached | Order notional exceeds max limit |
MaxTakerPriceDeviationBreached | Taker price exceeds max deviation from mark price |
OrderNotFound | Order hash not found |
OMFLessThanIMF | Post-execution open margin fraction below initial margin fraction |
MaxWithdrawAmountBreached | Collateral withdrawal exceeds max allowed amount |
MaxDDXWithdrawAmountBreached | DDX withdrawal exceeds max allowed amount |
TooMuchCollateralToWithdrawDDX | DDX withdrawal would violate collateral cap |
MaxInsuranceFundWithdrawBreached | Insurance-fund withdrawal exceeds max |
OrderPriceNeg | Order price is negative |
OrderAmountZeroNeg | Order amount is zero or negative |
OrderAmountNotMultipleOfMinOrderSize | Order amount is not a minimum-size multiple |
OrderTypeIncompatibleWithPrice | Order type and price fields are inconsistent |
PriceNotMultipleOfTickSize | Price is not a tick-size multiple |
UnsupportedMarket | Symbol is unsupported |
UnsupportedCurrency | Currency unsupported (USDC is required) |
TooManyOrders | Too many open orders for strategy/market |
WithdrawAmountZeroNeg | Collateral withdrawal is zero or negative |
WithdrawDDXAmountZeroNeg | DDX withdrawal is zero or negative |
WithdrawInsuranceFundZeroNeg | Insurance-fund withdrawal is zero or negative |
AccessDenied | Trader access denied |
CancelNoLiquidityForMarket | No open liquidity to cancel for symbol |
UnsupportedTraderUpdate | Trader update type unsupported |
MarketPriceNotAvailable | Mark price unavailable for symbol |
Realtime rejection surfaces
| Surface | Carrier | Notes |
|---|---|---|
| Subscription-control failure | ACKNOWLEDGE.result.error | Correlate by echoed request nonce; missing or mismatched nonce is anomalous control-plane behavior |
| Order-domain rejection | ORDER_UPDATE rejection fields | Connection may still be healthy |
| Strategy-domain rejection | STRATEGY_UPDATE rejection fields | Often linked to withdrawal attempts |
| Trader-domain rejection | TRADER_UPDATE rejection fields | Includes trader-level state actions |
421 and 503 note
NotAcceptingRequests and ServiceUnavailable are not generic placeholders. In the current runtime mappings they can represent leader/readiness transitions, pending durable-commit state, unavailable sequencing paths, or missing mark-price readiness. Treat them as recoverable service-state signals rather than as proof that the original payload was valid.
What this page does not replace
| Need | Use instead |
|---|---|
| step-by-step recovery procedure | How to Handle API Errors and Recovery |
| event-by-event lifecycle semantics | Order and Account Event Reference |
| family-level REST error framing | REST Errors |