Errors

One envelope, stable codes, and what to do about each.

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.

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–99.
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 and self-trade prevention 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.