Errors

Success envelope

Every successful response is wrapped in a data object:

{ "data": { "...": "..." } }

The shape inside data varies by endpoint (array, keyed object, single resource, or null) — see Groups & proposals → Response envelopes.

Error envelope

Every error returns a standard HTTP status code and a single, consistent JSON body:

{
  "statusCode": 422,
  "code": "INSUFFICIENT_FUNDS",
  "message": "Your wallet has 12.50 USDC but this order needs 25.00 USDC.",
  "retryable": false,
  "details": { "required": "25.00", "available": "12.50", "currency": "USDC" },
  "errorId": "8f3c2b1e-7a90-4c2d-9b1e-2f6a4c8d0e11"
}

Field	Always present	Meaning
`statusCode`	yes	The HTTP status (mirrors the response status line).
`code`	yes	A stable machine code — branch on this, never on `message`.
`message`	yes	Human-readable explanation. Wording may change; don’t parse it.
`retryable`	when applicable	`true` only when it is safe to resend the identical request (see below). Treat a missing value as `false`.
`details`	when applicable	Machine-readable context for the code (amounts, symbol, region, …). Money values are decimal strings.
`errorId`	yes	Unique per error; quote it in support requests.

message may occasionally be an array of validation strings — write your handler to accept either a string or a string array.

Response headers

Header	When	Use
`X-Request-Id`	every response	Correlation id. Echoes a value you send, or is generated. Log it.
`Retry-After`	`429` and retryable `5xx`	Seconds to wait before retrying.

Status codes

Status	When	What to do
`400 Bad Request`	Malformed / missing / invalid input.	Fix the request. Read `code`/`details`.
`401 Unauthorized`	Missing or invalid key.	Check the `Authorization: Bearer murmo_...` header.
`403 Forbidden`	Not a member, not the creator, geo-restricted, or in-app-only.	Don’t retry as-is.
`404 Not Found`	Unknown resource id (proposal, position, market, group).	Check the id.
`409 Conflict`	The resource’s state forbids the action (market closed, proposal/position closed, already claimed).	Re-read state; some are retryable (see `retryable`).
`422 Unprocessable`	Input is well-formed but breaks a trading rule (insufficient funds, min size, leverage, slippage).	Adjust the order.
`429 Too Many Requests`	Rate limit (1,200 / 60s) exceeded.	Back off using `Retry-After`.
`5xx`	Upstream rejected/unavailable or an unexpected server error.	Retry with backoff if `retryable`; report if persistent.

Retry semantics

retryable means “safe to resend the identical request — no funds moved and no order was submitted.” It is not a synonym for “transient.”

retryable: true — failures where nothing stuck: RATE_LIMITED, ROUTE_NOT_FOUND, NO_MARKET_PRICE, NO_LIQUIDITY, ORDER_NOT_FILLED, FUNDING_REFUNDED, REQUEST_IN_PROGRESS, SLIPPAGE_EXCEEDED, UPSTREAM_TIMEOUT, UPSTREAM_UNAVAILABLE. Retry with exponential backoff (honor Retry-After when present).
retryable: false — terminal. Fix the request; do not loop. In particular, after a write that may have been submitted, reconcile via /positions or /trades rather than retrying — a retry can double-submit (idempotency keys are coming in a future release).

Codes worth handling

The full machine-readable catalog (every code → status and retryable) is published as error-catalog.json, generated from the API’s error registry. The most common:

`code`	Status	Meaning
`INSUFFICIENT_FUNDS`	422	Not enough balance. `details` carries `required`/`available`.
`MARKET_CLOSED`	409	Market isn’t open for this action. `details.nextOpenAt` when known.
`MARKET_NOT_ACTIVE`	400	Prediction market isn’t accepting trades (closed, resolved, or not orderbook-enabled).
`AMOUNT_BELOW_MINIMUM`	400	Prediction buys must be at least $4.
`MIN_ORDER_SIZE`	400	Buy is below the market’s venue minimum (typically 5 contracts); the message carries the market’s dollar minimum.
`POSITION_BELOW_MIN`	400	Position is entirely below the venue’s sell minimum; it settles automatically at resolution.
`NO_LIQUIDITY`	422	No liquidity on the book right now. Retryable.
`ORDER_NOT_FILLED`	422	The order didn’t fill and funds were released. Retryable.
`FUNDING_REFUNDED`	422	A prediction buy’s funding failed and the money was returned. Retryable.
`ORDER_BELOW_MIN_SIZE`	422	Order rounds below the market minimum. Increase size.
`LEVERAGE_EXCEEDS_MAX`	422	Requested leverage above the market max.
`SLIPPAGE_EXCEEDED`	422	Fill would exceed slippage tolerance. Retryable.
`ROUTE_NOT_FOUND`	422	No swap route / no quote. Often transient — retry or adjust size.
`NOTHING_TO_SELL`	422	No position to sell/close for this proposal.
`NOT_CLAIMABLE`	422	Nothing claimable on this proposal. Note: on an `INVALID` (50/50) resolution BOTH sides are claimable at $0.50 per contract.
`REQUEST_IN_PROGRESS`	409	An identical write is already in flight. Retryable after it settles.
`NOT_GROUP_MEMBER`	403	You’re not a member of this group.
`GEO_RESTRICTED`	403	Product unavailable in your region.
`RATE_LIMITED`	429	Rate limit exceeded. Honor `Retry-After`.
`UPSTREAM_TIMEOUT` / `UPSTREAM_UNAVAILABLE`	504 / 503	A dependency timed out / is down. Retryable.
`VALIDATION_ERROR`	400	Invalid input. `details.fields` lists the offending fields.

Handling pattern

async function call(path, init) {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", ...init?.headers },
  });
  const body = await res.json().catch(() => ({}));
  if (!res.ok) {
    const err = new Error(`${body.code ?? res.status}: ${body.message}`);
    Object.assign(err, { code: body.code, retryable: body.retryable, details: body.details });
    throw err;
  }
  return body.data;
}

def call(method, path, **kw):
    res = requests.request(method, f"{BASE}{path}",
        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}, **kw)
    body = res.json() if res.content else {}
    if not res.ok:
        raise ApiError(code=body.get("code"), message=body.get("message"),
                       retryable=body.get("retryable", False), details=body.get("details"))
    return body["data"]

Branch on code, back off when retryable is true (honoring Retry-After), and treat retryable: false as terminal. For writes, reconcile via /positions or /trades instead of blind retries.

Get started

Example flows

Core concepts

Trading guides

Real-time (WebSockets)

Success envelope

Error envelope

Response headers

Status codes

Retry semantics

Codes worth handling

Handling pattern

​Success envelope

​Error envelope

​Response headers

​Status codes

​Retry semantics

​Codes worth handling

​Handling pattern

Success envelope

Error envelope

Response headers

Status codes

Retry semantics

Codes worth handling

Handling pattern