Errors

Envelope

Every error, on every endpoint, has the same shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description.",
    "details": {}
  }
}

Field	Use
`error.code`	Stable. Safe to branch on.
`error.message`	For humans. Can change without notice, so never match on it.
`error.details`	Surface-specific context, most often `details.reason`.

HTTP statuses

Status	Meaning	Your move
`400`	The request is malformed or a value is out of range.	Fix the request. Retrying will not help.
`401`	The credential is missing, invalid, revoked, or expired.	Check the key. Do not retry with the same one.
`403`	The credential is valid but not permitted to do this.	Check scopes, or the key format.
`404`	The object does not exist, is not yours, or has already been evicted.	Treat as normal on short-lived objects.
`409`	A state conflict. Something changed underneath you.	Re-read state and decide. Often not retryable.
`410`	The object expired and is gone, such as a cashout auction past its window.	Start a new one.
`413`	Payload too large.	Reduce the request body.
`429`	Rate limited.	Wait the seconds in the `Retry-After` header. Main API routes also put them in `error.retry_after`.
`500`	Something failed on our side.	Retry with backoff, unless the endpoint documents an indeterminate outcome. Then check state before you retry.
`502`	Partial success, such as `PARTIAL_VAULT_ONLY` on a withdrawal.	Read `error.details` before retrying. See Funding.
`503`	Temporarily unavailable.	Retry with backoff.

A parlay id you do not own returns 404, not 403, so the API never confirms that another account’s parlay exists. A quote request id you do not own returns 403.

Top level codes

`error.code`	Status
`VALIDATION_ERROR`	400
`UNAUTHORIZED`	401
`FORBIDDEN`	403
`NOT_FOUND`	404
`CONFLICT`	409
`GONE`	410
`PAYLOAD_TOO_LARGE`	413
`RATE_LIMITED`	429
`INTERNAL_ERROR`	500
`PARTIAL_VAULT_ONLY`	502
`SERVICE_UNAVAILABLE`	503

Authentication

Condition	REST	SSE	`details.reason`
Credential does not start with `api_`	`403`	`403`	`wrong_api_key_type`
Well-formed key, but invalid or revoked	`401`	`401`
Valid key, missing the required scope	`403`	`403`	`insufficient_scope`

The 403 for a malformed key carries a hint about the expected format. Keys match api_(live|test)_[A-Za-z0-9_-]{28,36}. The scope catalog is on Authentication.

Committing a quote

Returned by POST /v1/quote-requests/{id}/commit in error.details.reason. No commit failure moves funds: if the commit did not return success, the trade did not happen.

Reason	What happened	Your move
`QUOTE_CHANGED`	The request changed since the version you committed against.	Re-read the request and commit against the new version.
`QUOTE_EXPIRED`	Every quote on the request has expired, or the best quote expired between selection and commit.	Wait for a fresh `best_quote` event, then retry.
`MARKET_NOT_LIVE`	A leg’s market expired, halted, or was delisted.	Remove the affected leg. Retrying will not help.
`COMMIT_FAILED`	The commit could not complete, for example because no eligible maker had enough collateral.	Not retryable.
`COMMIT_FAILED_RETRYABLE`	A temporary failure.	Retry after a short delay.
`mm_confirmation_timeout`	The chosen maker did not confirm in time. Returned as `409`, with the maker in `failed_mm_id`.	The request stays open. Commit the next best quote, or leave that maker out with `exclude_mm_ids`.

Submitting a quote

Returned by PUT /v1/mm/quote-requests/{id}/quote.

Status	`details.reason`	Meaning
400	`insufficient_collateral`	The quote needs more collateral than you have free. Carries `required` and `available`.
503	`collateral_check_unavailable`	Your balance could not be verified. Retry.
503	`fee_unavailable`	The taker fee rate could not be read, so the quote was rejected rather than priced at 0 bps. Retry.
409	`version_mismatch`	Your `request_version` or `request_hash` is stale. Re-read the latest event and resubmit both.

Both 503s fail closed on purpose, so a quote is never admitted against a balance or fee rate that could not be read. Priced at an unknown fee, your odds would apply to the gross bet and you would underwrite more than you modeled.

Bidding on a cashout auction

Returned by PUT /v1/mm/cashout-requests/{id}/quote.

Status	`details.reason`	Meaning
400	validation	Non-integer or non-positive `price_micro`, `expires_in_ms` out of range, unknown field, or malformed JSON.
400	`price_above_max_payout`	Your bid exceeds `total_payout`. The response carries `max_price_micro`.
400	`price_above_buyback_bound`	You back this position and the bid exceeds what your collateral covers after the fee.
403	`insufficient_scope`	Your key lacks `mm:quote`.
404		The auction is unknown, or already evicted at its TTL (time to live). The normal “too slow” outcome.
409	`self_quote`	You opened this auction, so you are the seller. Bidding on a position you back is allowed: that win closes the position.
409	`not_active`	The auction was committed or cancelled before your bid landed.
409	`expired`	The auction expired as your bid landed.
409	`MARKET_NEAR_CLOSE`	The underlying market is too near its close to exit.
409	`buyback_wallet_missing`	You back this position but have no wallet on record, so a closing exit cannot be built. See below.

buyback_wallet_missing fails only your bids. Others can still win the auction as an acquisition, so do not blacklist the position.

Rejections you never see

These cashout rejections happen when the user commits, not when you bid. They never reach you as an HTTP response. You learn of them by not being filled.

Reason	Meaning
`amount_over_bound`	The fee-aware ceiling, re-checked at commit when the fee rate was unavailable at bid time.
`insufficient_buyer_balance`	You would acquire the position but your free balance does not cover it.
`buyer_no_vault`	You would acquire the position but have no vault.
`already_transferred`	The position had already moved.
`buyer_is_counterparty`	A safety check: your wallet already backs the position, so the win has to close it rather than acquire it.

Triage

Class	Treatment
`400`, `401`, `403`	Alert. These are your bug. If every request fails this way, you are silently out of the market.
`404` and race-class `409` (`not_active`, `expired`)	Log quietly. On short-lived objects these are ordinary lost races, not failures.
`429`	Back off for the seconds in `Retry-After`.
`500`, `503`	Retry with exponential backoff, unless the outcome is documented as indeterminate. Then check state first.

Separate 400 / 401 / 403 from 404 / 409 in your alerting from day one. Logged together, a losing auction and a broken integration look identical. A market maker whose key silently lost the mm:quote scope sees nothing but quiet 403s.

Overview

Quote service

Market maker

Markets

Parlays

Account

API keys

Funds and vault

Webhooks

Envelope

HTTP statuses

Top level codes

Authentication

Committing a quote

Submitting a quote

Bidding on a cashout auction

Rejections you never see

Triage

​Envelope

​HTTP statuses

​Top level codes

​Authentication

​Committing a quote

​Submitting a quote

​Bidding on a cashout auction

​Rejections you never see

​Triage

Envelope

HTTP statuses

Top level codes

Authentication

Committing a quote

Submitting a quote

Bidding on a cashout auction

Rejections you never see

Triage