Errors

{ "error": "quote_expired" }

{ "error": "invalid_request", "detail": [ { "path": ["side"], "message": "..." } ] }

{ "error": "insufficient_scope", "required": "orders:write", "message": "..." }

• error is always present and is the field to branch on.
• detail is present on validation and stake failures and carries the specific reason. On a quote refusal it is the only field beside error: a stake cap arrives inside that string as prose, not as a named field. There is no maxStake on the wire. Parse the code, show the detail, and re-quote at a smaller size rather than trying to read a number out of it.
• orderId is present on 409 quote_already_used and on nothing else. It names the order that spent the quote, and it is the only recovery path that code has.
• priceMove is present on 409 price_moved and on nothing else. It carries fromCents, toCents and adverseCents, so you can show the player what the price did without re-quoting to find out.
• required is present on insufficient_scope and names the scope the route wanted, so the fix never has to be guessed.
• message is prose for a log line. It is not stable and must not be parsed.

400: the request needs fixing

401 / 403: credentials, scope and eligibility

404: not found

409: the state moved

422: accepted shape, refused business rule

429, 5xx

Every paged feed answers a cursor it cannot decode with 400 invalid_cursor: /api/v1/events, /api/v1/orders, /api/v1/positions, /api/v1/settlements, /api/v1/reconciliation/feed and the sandbox GET /api/v1/users/{id}/ledger. One rule, one code, one status.

Three of those six used to restart at page one instead. What it cost: a consumer that stored a truncated cursor re-read its whole history and reported a successful page while doing it. They refuse now, so a bad cursor is something you see.

The gate produces RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every request it authorises, and most routes pass them back. Two that do not are POST /api/v1/quotes and POST /api/v1/orders, which answer without them on success and on failure alike. Several error paths elsewhere omit them too: the 404 for an unknown player, every 403 sandbox_only, and the 400 and 500 branches of the order reads.

So do not build a budget tracker that assumes a header on every reply. Read them where they arrive, keep your own count between reads, and treat a 429 as the authoritative signal. The 429 body always carries retryAfterSeconds and the response always carries Retry-After.

Named here because they appear in most payments-shaped API specifications, and their absence is a fact worth knowing rather than a gap to discover in production.

// Branch on the class of failure, not on the status code alone.
function classify(status: number, error: string) {
  if (error === 'reconciliation_required') return 'hold';  // do NOT release, do NOT re-quote
  if (status === 409) return 'requote';                    // price moved or quote spent
  if (status === 429 || status >= 500) return 'backoff';
  if (status === 401 || status === 403) return 'credentials';
  return 'fix';                                            // 400 and 422: retrying changes nothing
}

• hold: keep the authorization, poll GET /api/v1/orders/{id} and act only when settlementState is settled. If you never received an orderId, find it with GET /api/v1/orders?externalUserId=&clientOrderId=.
• requote: start a new quote. Show the player the new price before submitting.
• backoff: exponential, with jitter. For an order, resubmit with the same clientOrderId; that is what makes the retry free.
• credentials: read required on an insufficient_scope and issue a key that carries it. Waiting fixes nothing.
• fix: never retry unchanged. A 422 retried in a loop is a loop.

The SDK raises these as typed errors, so the classification above is already made for you. ReconciliationRequiredError carries holdAuthorization: true, RateLimitError carries retryAfterSeconds, InsufficientScopeError carries required, and QuoteAlreadyUsedError carries the colliding orderId. See the SDK.

The limiter runs on every /api/v1 route and every response carries the current window on three headers, whether it succeeded or not. It is documented in full on Rate limits. Read it before you write your polling loop: a second ceiling binds every key you hold together, and the headers on this response do not describe it.