Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Refusals

A request can be refused in two places:
  • The gateway checks what the settlement contract will check: signature, signing key, nonce range and floor, the instrument, the ladder, the fee cap and the expiry, and the account's rate and size limits. A refusal is HTTP 422 with {"error": "<reason>"}, and nothing reaches the engine.
  • The engine decides everything else: cash, nonce reuse, the instrument's state, the account's caps. Its refusal is a code, for example INSUFFICIENT_CASH: in the order's code (with ?wait), in a refused event on the WebSocket, as a cancel's or a quote request's status, or as the error of a withdrawal's 422.
A nonce the engine accepts is spent even if the order is then refused for another reason, so a refused order cannot be resent under the same nonce. Sign it again under a new one.
Rate limits are 429, and holds and outages 503: see Errors and Rate limits.

Gateway reasons

Signatures and keys

ReasonWhat to do
signature: …, signature does not recover, bad signature hexThe signature is malformed, has a high s, or is not over these exact terms and this domain.
signed by a key not registered for the maker, or expiredSign with the account's own key, or register this key with setSigningKey and wait a few seconds for its block to be read.
signed by another key: only the account's own mayA withdrawal request must be signed by the account itself.
the order outlives its signing key: …Shorten expiresAt, or extend the key.

Nonces

ReasonWhat to do
nonce must be in [1, 2^62)See Nonces.
nonce names shard N; this engine is shard 0Bits 54–61 of the nonce must be zero.
nonce below the maker's on-chain floor, nonce below the account's on-chain floorYou raised your floor with cancelUpTo; use a nonce above it.

Orders

ReasonWhat to do
bad order termsside is not 0 or 1, or size is 0.
specifier names no listable contractThe specifier does not decode to a listed strike, European style and multiplier 100.
no such instrumentWell-formed, but not listed. Check GET /v1/instruments.
price is off the ladderSee the tick ladder.
order outlives its contractexpiresAt is after the contract's expiry.
order already expiredexpiresAt is in the past.
fee cap below the instrument's feesRaise maxFeePerMille so that ten times it is at least both of the instrument's rates.
maxFeePerMille is a uint8 counting tens of basis points: at most 255
size exceeds the engine's maximum orderAt most 230 contracts.
N orders of M lots in all may make M fills at once …; this account's class allows B …The order, or the batch's orders summed, is larger than the account's whole fill burst: 100 contracts for an ordinary account on the testnet. Split it over time. See Account classes.
N orders and M cancels cost C of the signed rate at once; this account's class allows B …The batch costs more than the class's whole signed burst. Send it in smaller batches.
wait: milliseconds?wait is not a whole number of milliseconds.
bad json: …The body did not decode, or a number was sent as a string.

Accounts

ReasonWhat to do
no engine account for the maker: deposit first, unknown accountYour first deposit opens your account.
account inactiveThe account is deactivated or frozen.

Batches

ReasonWhat to do
a batch holds 1..256 members
member N: an order or a cancelEach item holds exactly one of order and cancel.
member N: a batch is one maker'sEvery item in a batch must have the same maker.
member N: <reason>Member N (from 0) failed with <reason>; nothing in the batch was sent.

Quote requests

ReasonWhat to do
side must be 0 (buy), 1 (sell) or 2 (none)
size must be in [1, 2^30]

Sessions and reads

ReasonStatusWhat to do
an address, address, challenge and signature, signature: 65 bytes of hex422A field is missing or malformed.
session: the challenge is not one this exchange issued, or has expired401Ask for a new challenge: each lasts 5 minutes.
session: the signature is not the address's, nor a key it registered401Sign the message exactly as returned, with personal_sign.
a session for this address is required …401Send Authorization: Bearer <token>.
the session is another address's403
nonce: an integer, underlyingKey and specifier: integers, before: …, state: resting …422A path or query parameter is malformed.

Withdrawals

ReasonWhat to do
bad requestThe body did not decode, or amount is not above 0.
INSUFFICIENT_CASH and the other engine codesThe engine refused the debit.

Engine codes

The codes a participant can meet:
CodeMeaning
INSUFFICIENT_CASHFree cash does not cover what the order adds to the account's requirement (see Security), or a withdrawal exceeds free cash.
INVALID_PRICEThe price is off the ladder.
PRICE_ABOVE_MAX_PAYOFFAbove 1000000 − K for a call or K for a put.
INVALID_QUANTITYThe quantity is out of range.
INSTRUMENT_NOT_ACTIVEThe contract is halted or settling. Cancels are still accepted.
BOOK_NOT_LIVEThe contract's book is no longer open: it is settling or settled.
ORDER_EXPIREDThe order's expiry had passed by the time the engine applied it.
OPEN_ORDER_LIMITThe account already has its class's cap of resting orders, and this order could rest. Cancel some, or send one with a zero lifetime. See Account classes.
BOOK_LIMITThe order would open a book (an underlying at one expiry) past the account's class's cap.
NONCE_USEDThis nonce has already been used by this account, for an order, a cancel, a quote request or a withdrawal. With ?wait, order says where the order that used it stands.
NONCE_BELOW_WINDOWThe nonce is more than 4096 below the highest this account has used. Keep nonces increasing.
NONCE_OUT_OF_SPACEThe nonce is zero or outside the account range.
NONCE_BELOW_FLOORBelow the floor set on chain with cancelUpTo.
ORDER_NONCE_NOT_FOUNDA cancel named an order that is not resting: it filled, expired, was cancelled, or never rested.
ORDER_OUTLIVES_KEYThe order would rest past its signing key's expiry.
SIGNING_KEY_INVALIDThe signing key is not registered for the account, or has lapsed.
ACCOUNT_NOT_ACTIVEThe account is deactivated or frozen.
UNDERLYING_KEY_MISMATCHThe underlyingKey does not name the contract's underlying.
ORDER_POOL_FULL, POSITION_POOL_FULL, POSITION_LINE_POOL_FULLThe engine is at capacity. Try again later.
Every other code names a fault in the request's encoding or an administrative condition, and is listed in the engine's source.