Errors

Every error has the same shape:

{
  "error": {
    "code": "insufficient_balance",
    "num": 257,
    "origin": "core",
    "message": "…",
    "details": null
  }
}

Branch on code, never on message. Codes are stable; messages are not.

`origin` tells you whether it happened

This is the field worth understanding, because it answers “did my order exist?”

`origin`	Meaning
`gateway`	Rejected at the edge, before sequencing. Never happened.
`port`	Rejected at the order-entry edge. Never happened, no record exists.
`core`	The exchange sequenced your request and rejected it. It happened, and it is in the audit log.

For a retry decision: gateway and port rejects are safe to fix and resend. A core reject is a real economic answer, resending unchanged gets the same result.

Common codes

Authentication

Code	HTTP	What to do
`unauthorized`	401	Bad signature, unknown key, or clock skew, all identical by design. Work through the checklist.
`missing_scope`	403	Your key lacks the scope. On `/v1/withdrawals` this is expected, bot keys cannot withdraw.
`rate_limited`	429	Back off by `details.retry_after_ms`. See Rate limits.

Your request was malformed

Code	HTTP	What to do
`unknown_field`	400	An unrecognised field. Schemas are closed, check for typos.
`schema_violation`	400	Missing or wrong-typed field.
`malformed_json`	400	Body did not parse.
`bad_price_tick`	400	`tick` must be an integer 1–9999 and on the live grid (interior whole cents, wings 0.10¢). Old `1`–`99` fails.
`bad_qty`	400	Quantity must be a positive whole number.

The exchange said no

Code	HTTP	What to do
`insufficient_balance`	422	Not enough available balance.
`sell_exceeds_position`	422	Selling more than you hold.
`max_cost_exceeded`	422	A market buy would exceed `max_cost`.
`duplicate_client_order_id`	409	Already used. If this follows a timeout, the original order exists, do not resend with a new id.
`unknown_order`	404	Already filled, cancelled, or never existed.
`market_not_found`	404	Wrong `market_id`, it is recycled, so re-read the round.
`market_frozen`, `market_closed`, `trading_paused`, `exchange_paused`	409	The round stopped accepting orders. Move to the next round.
`user_suspended`	403	Risk action against the account. Not retryable.
`open_order_cap`, `per_market_limit`	403	You hit a position or open-order limit.

Timeouts are not rejections

Code	HTTP	What to do
`sequencing_timeout`	504	Your order may still exist. Retry with the same `client_order_id`, or `GET /v1/portfolio/orders?client_order_id=…`.
`shed`	503	The write path is saturated. Back off and retry.

A 504 is the one case where “it failed” is the wrong assumption. The request timed out waiting for sequencing; it may well have been sequenced. Always resolve it with the same client_order_id, that is what the idempotency key is for. Retrying with a fresh id is how you end up with two orders.

Cancellations are not errors

Post-only orders that would cross, unfillable FOKs, IOC remainders, self-trade prevention, and off-grid rests after a tick-grid coarsen all come back as a successful 201 with status: "canceled" and a reason. They are execution outcomes, not failures, so check status on success responses rather than assuming 201 means resting. reason: "tick_size" means the rest was cancelled because it was no longer on the live grid.

Full error registry

Branch on code. The table below is the full registry the venue emits today.

Gateway (`origin: "gateway"`, `num: null`)

Code	HTTP	Meaning
`unauthorized`	401	Bad signature, unknown key, stale timestamp, or revoked key
`missing_scope`	403	Key lacks the required scope
`rate_limited`	429	Token bucket empty, back off by `details.retry_after_ms`. See Rate limits.
`unknown_field`	400	Unrecognised request or query field (closed schema)
`schema_violation`	400	Missing or wrong-typed field
`malformed_json`	400	Body did not parse as JSON
`unexpected_body`	400	Body sent where none is allowed (e.g. cancel-all)
`bad_price_tick`	400	`tick` not an integer 1–9999, or off the live rest grid
`bad_qty`	400	Quantity not a positive whole number
`max_cost_required`	400	Market buy missing required `max_cost`
`bad_amount`	400	Withdrawal `amount` zero or non-numeric
`bad_destination`	400	Withdrawal `dest` not valid hex address shape
`bad_client_withdrawal_id`	400	Withdrawal id zero or unparsable
`stale_client_withdrawal_id`	409	Withdrawal id not strictly increasing
`batch_too_large`	400	Batch exceeds 20 items, nothing fires
`not_found`	404	Unknown route or unparsable path segment
`market_not_found`	404	Market does not exist (edge read)
`unknown_order`	404	Order unknown, foreign, or evicted (edge read)
`round_not_found`	404	No round in ring for this id
`unknown_withdrawal`	404	Withdrawal id not found
`key_table_stale`	503	Key table not yet loaded
`shed`	503	Write path saturated, back off and retry
`sequencing_timeout`	504	Timed out waiting for sequencer, order may exist

Core (`origin: "core"`, `num` set)

Sequenced rejects, the request happened and is in the audit log.

Code	HTTP	`num`	Meaning
`insufficient_balance`	422	257	Not enough available balance
`sell_exceeds_position`	422	258	Selling more than held
`max_cost_exceeded`	422	259	Market buy would exceed `max_cost`
`market_closed`	409	513	Market not accepting orders
`market_inactive`	409	514	Market inactive
`market_not_found`	404	515	Market does not exist
`exchange_paused`	409	516	Exchange paused
`trading_paused`	409	517	Trading paused on this market
`market_frozen`	409	518	Round frozen
`bad_price_tick`	400	769	Invalid tick
`bad_qty`	400	770	Invalid quantity
`duplicate_client_order_id`	409	771	Idempotency key already used
`unknown_order`	404	772	Order not found for cancel/decrease
`unsupported_characteristic`	400	773	Unsupported order flag combination
`invalid_decrease`	400	774	Invalid decrease request
`book_full`	503	775	Order book at capacity
`per_market_limit`	403	1025	Per-market position limit
`group_limit`	403	1026	Group limit exceeded
`open_order_cap`	403	1027	Too many open orders
`user_suspended`	403	1028	Account suspended
`reduce_only_violation`	403	1029	Reduce-only order would increase exposure

Port (`origin: "port"`)

Edge rejects at the order-entry port, never sequenced, no stream record.

Code	HTTP	`num`	Meaning
`bad_price_tick`	400	769	Invalid tick (port edge)
`bad_qty`	400	770	Invalid quantity (port edge)
`duplicate_client_order_id`	409	771	Duplicate coid (port edge)
`unknown_order`	404	772	Unknown order (port edge)
`unsupported_characteristic`	400	773	Unsupported flags (port edge)
`invalid_decrease`	400	774	Invalid decrease (port edge)
`rate_exceeded`	429	1538	Port static rate limit
`market_not_permitted`	403	1539	Market not permitted for this user
`size_cap_exceeded`	403	1540	Order size cap exceeded
`client_order_id_required`	400	1541	Missing `client_order_id`
`funding_capacity`	503	null	Funding port at capacity

Funding-port rejects carry origin: "port" but num: null, funding reject codes use a separate enum, not the shared registry.

Get started

SDKs

Strategies

Concepts

Changelog

`origin` tells you whether it happened

Common codes

Authentication

Your request was malformed

The exchange said no

Timeouts are not rejections

Cancellations are not errors

Full error registry

Gateway (`origin: "gateway"`, `num: null`)

Core (`origin: "core"`, `num` set)

Port (`origin: "port"`)

​origin tells you whether it happened

​Common codes

​Authentication

​Your request was malformed

​The exchange said no

​Timeouts are not rejections

​Cancellations are not errors

​Full error registry

​Gateway (origin: "gateway", num: null)

​Core (origin: "core", num set)

​Port (origin: "port")

`origin` tells you whether it happened

Common codes

Authentication

Your request was malformed

The exchange said no

Timeouts are not rejections

Cancellations are not errors

Full error registry

Gateway (`origin: "gateway"`, `num: null`)

Core (`origin: "core"`, `num` set)

Port (`origin: "port"`)