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, including maxStake when a stale-price cap is what refused you.
• 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

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 — ReconciliationRequiredError carries holdAuthorization: true, RateLimitError carries retryAfterSeconds, InsufficientScopeError carries required — so the classification above is already made for you. 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.