Errors & rate limits

OCX uses standard HTTP status codes with a JSON error body. Always branch on the status code first, then read the body for detail.

Error shapes

The body depends on which layer answered.

{
  "error": "INSUFFICIENT_MARGIN",
  "message": "…",
  "details": { "reason": "…" }
}

{ "message": "Bad Request: INSUFFICIENT_MARGIN: …" }

{ "message": "Unauthorized" }

Options business rejections carry the code in error.
Futures business rejections carry the code inside message, after the status text ("Bad Request: <CODE>: <detail>").
Gateway errors (authentication, validation, routing) carry only message. A request that fails schema validation returns 400 with the offending field in message.

New codes may be added over time — treat an unrecognized code as a generic failure of its status class.

Status codes

Status	Meaning	What to do
`200` / `201`	Success	Read the response body.
`202`	Accepted, not final (for example a deposit awaiting confirmations)	Check back later.
`400`	Bad request or business rejection — malformed body, invalid value, insufficient margin or balance	Fix the request or handle the code; don’t retry unchanged.
`401`	Not authenticated — missing, expired, or revoked session	Sign in again with SIWE.
`403`	Forbidden — for example a futures quote route (`QUOTES_MARKET_MAKER_ONLY`), or a cookie-authenticated request from another website	Use the right endpoint; call from your own server.
`404`	Unknown route, market, order, or record	Verify the path and id.
`409`	Conflict — `IDEMPOTENCY_CONFLICT`, an amend that raced a fill, or a transfer refused while you have open positions or orders	Reconcile state, then decide.
`422`	Multi-leg strategy rejected (`leg_match_failed`, `insufficient_margin`)	Re-price or resize the legs.
`429`	Gateway rate limit	Back off until the window resets.
`502` / `503` / `504`	Upstream unavailable, degraded, or timed out (`503` bodies carry `code: "HOT_PATH_DEGRADED"`)	Retry with backoff; reconcile order state before resubmitting.

Common business rejections

These come back on trading and wallet endpoints. They are expected outcomes, not bugs — handle each deliberately.

INSUFFICIENT_MARGIN

The order would breach your margin. Every order passes a server-side margin check before acceptance. If the shortfall is only collateral sitting elsewhere in your account, the gateway moves it and retries once before you see this. Otherwise reduce size or deposit. Options rejections include details.reason.

EXIT_COST_EXCEEDS_EQUITY

Options: opening this position would leave you unable to close it at current book prices without taking your account to the liquidation line.

POST_ONLY_WOULD_TAKE

A postOnly order would have taken liquidity, so it was rejected to keep you on the maker side. Re-price behind the touch and resubmit.

REDUCE_ONLY_VIOLATION

A reduceOnly order would have increased your position (wrong side, or already flat). Check your position before retrying.

FOK_NOT_FILLABLE / MARKET_NO_LIQUIDITY

A fok order could not fill in full, or a market order found nothing to take. Nothing executes; adjust price or time-in-force.

PRICE_OUT_OF_BAND

Futures: a limit price too far through the mark and the opposite side of the book.

MARKET_NOT_TRADING / MARKET_HALTED / MARKET_EXPIRED

The market is halted or past expiry (MARKET_NOT_TRADING on futures; MARKET_HALTED / MARKET_EXPIRED on options).

INVALID_PRICE / INVALID_QUANTITY

A price off the tick, a missing limit price, or a quantity that is not a positive whole number of contracts.

IDEMPOTENCY_CONFLICT

You reused a clientOrderId with different order parameters. A retry with identical parameters returns the original result instead.

RATE_LIMITED

The engine’s per-account order rate limit. Returned as 400, not 429; options responses include retryAfterMs.

leg_match_failed

A multi-leg strategy could not fill every leg immediately. Strategies are all-or-none — nothing executes. The body names failedLegIndex.

Insufficient {bucket} balance

A transfer or withdrawal exceeds the available balance. Returned as 400 from the wallet endpoints.

A business rejection is not a transport failure. Retrying it unchanged will fail the same way and can burn your rate budget — fix the cause first.

Rate limits

The gateway limits requests per client in one-minute windows:

Scope	Limit
Most endpoints	600 requests per minute
`/auth/*`	10 requests per minute per IP
`/wallet/*`	20 requests per minute
Futures market data and futures streams (`/fut/markets`, `/fut/orderbook`, `/fut/book-stream`, `/fut/market-stats`, `/fut/ohlc`, `/fut/trades`, `/fut/stream/*`, …)	Not rate-limited at the gateway

Rate-limited responses carry:

Header	Meaning
`x-ratelimit-limit`	Requests allowed in the current window
`x-ratelimit-remaining`	Requests left in the window
`x-ratelimit-reset`	Seconds until the window resets

When you exceed a limit you receive 429 with a retry-after header and a body { statusCode, error, message, retryAfter } (seconds). Order placement is additionally limited per account by the engines (RATE_LIMITED, above).

Handling 429 in practice

async function call(url, opts, attempt = 0) {
  const res = await fetch(url, opts);
  if (res.status === 429 && attempt < 5) {
    const retryAfterS = Number(res.headers.get("retry-after")) || 0;
    const waitMs = Math.max(retryAfterS * 1000, 250 * 2 ** attempt);
    await new Promise(r => setTimeout(r, waitMs));
    return call(url, opts, attempt + 1);
  }
  return res;
}

# --retry honours Retry-After on 429
curl -s --retry 5 --retry-delay 1 "https://api.ocx.global/markets/board?underlying=SPX"

Do not tight-poll. Prefer the streaming endpoints for live books, fills, the option board, and balances — one SSE connection replaces many polling requests.

Idempotency

Send a clientOrderId on orders. If a response is lost and you retry with the same clientOrderId and parameters, you get the original result rather than a duplicate order. Reconcile by reading your orders rather than assuming a lost request failed.

​Error shapes

​Status codes

​Common business rejections

​Rate limits

​Handling 429 in practice

​Idempotency

Error shapes

Status codes

Common business rejections

Rate limits

Handling 429 in practice

Idempotency