Errors, retries & idempotency

Error shapeCopy Anchor Link

Errors return JSON with a readable message. Quote and trading errors can add a stable code:

{ "message": "Quote has expired", "code": "quote_not_found" }

Branch on 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:

{ "statusCode": 400, "message": "Request validation failed", "errors": [{ "field": "sizeRaw", "message": "..." }] }

HTTP statusesCopy Anchor Link

Quote and fill codesCopy Anchor Link

These appear on 400 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 retriesCopy Anchor Link

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:

1. Keep the same quoteId. Poll GET /execution/status?quoteId=, or resend the fill with that quoteId.
2. Orders in the status response mean the fill was accepted. Track it to a terminal status.
3. A 404 from status means no orders are recorded yet. The original request may still be running, so treat the result as unknown and keep polling.
4. Treat the fill as not executed only when the quote's lifetime has passed, status for that quoteId still returns 404, and a resend with the same quoteId returns quote_not_found or quote_expired. Only then get a new quote.

Generate one 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 claimsCopy Anchor Link

A 4xx 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 400 writes an order or uses up the clientOrderId.
• Withdrawal: a 400 for an unviable price leaves a failed withdrawal that never moves funds. Send a requestId. With it, every other 400 writes nothing. Without it, a hand-off to execution that fails is also returned as 400 with a failed record, and funds can still move in rare cases.
• Claim: no 4xx writes a claim.

A timeout or 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 limitsCopy Anchor Link

A 429 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.