Errors

HTTP

Errors come back as JSON with a detail field saying what went wrong.

Status	Means
400	A parameter is wrong, such as both slug and id, no filter on /api/markets/markets, both limit and count on /api/markets/schedule, an after or before that names no market, or an asset or duration the route doesn’t list.
401	The request isn’t signed properly. See API keys.
403	The account in the path isn’t yours.
404	No such market, or /api/market-data/book for a market that is closed.
413	The request body is over 64 KiB.
422	A parameter is missing, the wrong type, or a market id or timestamp outside the 64-bit integer range. detail lists them.
429	Too many requests. Wait the seconds in Retry-After. See Rate limits.
503	A service behind the route is briefly unavailable. Try again after the seconds in Retry-After, if it has one.

Sockets

• Handshake refused with 401: the /ws/trade handshake isn’t signed properly.

• error message on /ws/trade: a message you sent could not be read (parse error: ...), or your key was revoked (api key revoked, and the socket closes). A signature that is not 0x and 128 hex digits gets a parse error. So does a field the gateway does not know, such as a signed_at_ms or a nonce on an order.

• Market data handshake refused with 503: the server is not ready. Wait the seconds in Retry-After, plus a random delay. Then try again.

• error message on /ws/market-data: the server could not act on a request, and the socket stays open. The code is bad_request, empty_subscription, too_many_subscriptions or catching_up. See the market data reference.

• Market data closed by the server: the close code says why. Connect again after a random delay. Then subscribe again.

  • 1001: the server is restarting.
  • 1008: no subscribe in 30 seconds, or too many requests waiting.
  • 1011: no answer to a ping.
  • 1013: you fell behind, or the server dropped you under load.

  See Closing.

Order rejections

An order_rejected message means nothing happened: the order, change or cancel was refused.

reason	Means
insufficient_collateral	The order would take your worst case below zero. See Orders.
rate_limited	Too many orders and changes from your account. See Rate limits.
market_not_open	The market isn’t trading. It isn’t listed yet, or it is closed or settled. A place or modify also gets it at or after the market’s end.
market_halted	Trading is halted, so a place or modify is refused. A cancel is still taken. The rejection has no seq. See Halted trading.
price_off_tick	The price isn’t a whole number of cents (a multiple of 100).
duplicate_client_order_id	You already used this client_order_id in this market. The order may have filled or been cancelled.
unknown_order	No resting order of yours has this client_order_id in this market. A modify of an expired gtd order also gets this.
version_changed	The version of a modify is not the order’s current version plus 1. See Orders.
expiry_passed	A gtd order’s expiry_ms is already past.
expiry_too_soon	A gtd order’s expiry_ms is less than 4 seconds ahead of the gateway’s clock.
post_only_would_cross	A post_only order would have filled on arrival.
fill_or_kill_would_not_fill	A fok order could not fill completely.
market_would_not_fully_execute	A fok market order could not fill completely.
market_cannot_rest	A market order had gtc or gtd. Use ioc or fok.
unsupported_quantity_unit	A cash-sized order that wasn’t a bid.
zero_quantity	quantity was 0.
quantity_too_large	quantity is beyond what the exchange accepts.
book_full	The market’s book has no room for another resting order.
client_order_id_too_large	client_order_id is above 2^63 − 1.
market_id_too_large	market_id is above 2^63 − 1.
max_fee_below_market_rate	The max_fee_bps of a place is below the market’s taker_fee_rate_bps. The rejection carries taker_fee_rate_bps. Sign the order again with a max_fee_bps of at least that. See Fees.
signature_required	session_key or signature is missing.
session_key_unknown	No live session key with this address belongs to your account. The request can also be before the key’s issued_at_ms. Or the gateway has had no list of keys for 5 seconds, and a place or modify is refused. A cancel from a key it already held still works.
session_key_expired	The session key has expired, or it expires in 5 seconds or less.
signature_invalid	The signature does not match the message and the key, or its s is above n/2.

The last four rows are about the signature. See Signing orders for what to do about each.

A few rejections come with a sentence rather than a code: an invalid price, an expiry_ms above 2^63 − 1, or the exchange being briefly unavailable. When the gateway refuses an order, the engine never saw it, so the rejection has no seq. The gateway sends those sentences, expiry_too_soon, max_fee_below_market_rate, insufficient_collateral, rate_limited, client_order_id_too_large, market_id_too_large, market_halted and the signature rejections. It also sends market_not_open for a market that isn’t listed as trading, or for a place or modify at or after the market’s end. If the engine refuses with market_not_open, the rejection has a seq.

Unfilled orders

order_unfilled means part of an order could neither fill nor rest, and was dropped. The rest of the order was fine.

reason	Means
immediate_or_cancel	An ioc order filled what it could.
market_no_liquidity	A market order found nothing more to take, at its worst price or better.
market_remainder_below_one_lot	A cash-sized market order had less than one lot’s worth left.
limit_remainder_below_one_lot	A cash-sized limit order had too little left to rest one lot at its price.

Rate limits

What	Limit	Over it
Orders and changes on /ws/trade, per account	50 a second, in bursts of up to 200.	order_rejected with rate_limited.
Cancels on /ws/trade, per account	500 a second, in bursts of up to 5,000.	order_rejected with rate_limited.
Account requests under /api/trading, per account	20 a second.	429, with Retry-After.
Any request under /api, per IP address	200 every 10 seconds.	429, with Retry-After.
Socket connections, per IP address	30 a minute.	The handshake is refused with 429.

Every socket and key on one account shares that account’s limits.