Error shape
Errors return JSON with a readablemessage. Quote and trading errors can add a stable code:
code when it is present, and always show or log message. Some errors carry only a
message. A few 400 messages start with a stable token such as
app_fee_override_requires_api_key:; match on that prefix.
A body that fails schema validation returns 400 with a different shape and no code:
HTTP statuses
Quote and fill codes
These appear on400 responses from GET /orderbook/{venueMarketOutcomeId}/route,
POST /execution/fill, POST /execution/orders, and POST /execution/limit-orders. The same
condition returns the same status and code on all three order routes: for example, a cash
balance that does not cover the order is always 400 with quote_insufficient_balance, and a venue
account or execution mode that changed while the order was being placed is always 400 with
quote_unfillable.
A rejected fill is remembered for the rest of the quote’s life. Sending the same
quoteId again
returns the same error. For quote_not_found and quote_expired, do not get a new quote until
step 4 below. For any other code in the table, get a new quote only when that row says to.
Idempotency and safe retries
POST /execution/fill has no separate idempotency key: one quoteId can create at most one set of
orders, so resending the same quoteId is always safe. Never get a new quote to retry a fill whose
result you do not know, or you can trade twice.
After a timeout on POST /execution/fill:
- Keep the same
quoteId. PollGET /execution/status?quoteId=, or resend the fill with thatquoteId. - Orders in the status response mean the fill was accepted. Track it to a terminal status.
- A
404from status means no orders are recorded yet. The original request may still be running, so treat the result as unknown and keep polling. - Treat the fill as not executed only when the quote’s lifetime has passed, status for that
quoteIdstill returns404, and a resend with the samequoteIdreturnsquote_not_foundorquote_expired. Only then get a new quote.
externalId per intended trade, store it before you send the request, and reuse it
across retries. A direct order the venue refuses after acceptance still uses up its externalId.
Limit orders, withdrawals and claims
A4xx on these routes means the request started nothing that can place an order or move funds,
now or later, with the one withdrawal exception below. 401, 403, 409 and 429 write nothing.
For 400:
- Limit order: no
400writes an order or uses up theclientOrderId. - Withdrawal: a
400for an unviable price leaves afailedwithdrawal that never moves funds. Send arequestId. With it, every other400writes nothing. Without it, a hand-off to execution that fails is also returned as400with afailedrecord, and funds can still move in rare cases. - Claim: no
4xxwrites a claim.
5xx is unknown, not a failure. The server keeps working after your client gives up,
and the record is written before the response, so it can exist even though you got no answer.
Do not wait for “no row” to become final. There is no fixed time after which a missing row is
proven. The resend is the check.
A
200 on a limit order does not mean it will rest. A venue can still refuse it after it is
accepted. The order then ends failed and keeps its clientOrderId.
A requestId is remembered permanently and is not returned on any response. The same
requestId and body replays the original withdrawal, even long after the preview’s
quoteExpiresAt, and even when that original failed. Use a new requestId for a new attempt. The
body comparison covers amountRaw, tokenSymbol, destinationChainId and
destinationAddress.
Reads (GET) are always safe to retry.
Rate limits
A429 carries Retry-After in seconds. Wait that long before retrying. Server calls with a
validated x-app-api-key get their own budget. See
Rate limits.