Errors

{ "error": "quote_expired" }

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

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

{ "error": "over_wager_limit", "detail": "...", "maxStake": 50 }

• error is always present and is the field to branch on.
• detail is present on validation, quote and order refusals and carries the specific reason as prose for a person. Do not parse numbers out of it: the figures a client can act on are named fields, listed below.
• maxStake (a number, major units) is present on 403 over_wager_limit and 422 stake_exceeds_stale_limit: the largest stake that would be accepted. Re-quote at or under it.
• maxCents is present on 409 line_not_available: the executable price, in cents, that put the line outside the wagerable band. It is a price, not an amount of money, which is why it is not called maxStake.
• retryAfterMs is present on 409 over_tenant_exposure: how long until the window that is full rolls over.
• requestedStake and supportedStake are present on 409 stake_exceeds_available_depth: what you asked for, and the largest stake the book can fill at these terms.
• sellableContracts and minimumContracts are present on 422 insufficient_position and 422 below_venue_minimum when a live cash out is refused at quote time: the most contracts the player could sell now, and the smallest sale the market accepts.
• orderId is present on 409 quote_already_used, where it names the order that spent the quote, and on 409 idempotency_conflict, where it names the order that already holds your clientOrderId.
• 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. On POST /api/v1/embed-sessions it is an array (that route needs three scopes) and a missing array beside it names the ones your key lacks.
• retryAfterSeconds is present on every 429, and so is the Retry-After header. They carry the same number of seconds.
• message is prose for a log line. It is not stable and must not be parsed.

The request id

Most partner responses, success and failure alike, carry a parity-request-id header: a fresh random value Parity attaches as the response goes out. The 429s from the image and embed-session limits do not.

Quotes and orders are different, because those are the calls a dispute is about. On POST /api/v1/quotes and POST /api/v1/orders you may send your own id in an x-request-id header: 1 to 128 characters of letters, digits, ., _, : and -. Parity uses it when it is well formed and mints a random one when it is absent or is not, and either way the response carries it in both x-request-id and parity-request-id, success and refusal alike. That id is stored with the quote, the order and any refusal, so Parity support can find the call by it. It is yours to choose, so it is not unique: keep it unique per call if you want it to identify one.

When you report a problem, send the request id together with what else identifies the call: the route, the time (UTC), the player's externalUserId, and the quoteId, orderId or your clientOrderId where there is one, with the error code you received.

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

Embed-session and price-stream codes

A request made with an embed session (Authorization: Embed <token>) on the embed surface, or on GET /api/v1/stream/prices when a session is presented, is refused with one of these. The embed-session mint itself adds two 422s.

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.

Refusing is what makes a bad cursor visible: a consumer that stored a truncated cursor sees a 400 rather than silently re-reading its whole history as a successful page.

The gate produces RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every request it authorises, and most routes pass them back. These answer without them:

• Every 400 and 500 from /api/v1/events.
• Every response from the funding routes and the sandbox controls.
• Every 403 sandbox_only, 404 unknown_user and 404 unknown_deposit.

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. Every 429 carries Retry-After and the same figure as retryAfterSeconds on the body.

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 authenticated /api/v1 route, and most responses carry the key's current window on three headers (the exceptions are listed above). 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.