Error Reference

Every error a Rails API returns carries a code and a slug. Branch on the code; the message is for people.

Every error response names its condition twice: code, a string such as "SYS-0003": a three-letter scope and four digits, and slug, an upper-snake name such as TOO_MANY_REQUESTS. The two always travel together and always mean the same thing. The human-readable text next to them may change wording without notice, so a client branches on code (or slug), never on the text.

Where the pair appears:

Transport	Shape
REST	{"error": {"slug", "code"}, "message"}
WebSocket command response	data.error is {"slug", "code"}, data.body holds the text, data.clientRequestId echoes yours
WebSocket frame outside any command (a dropped or throttled message)	{"statusCode", "body", "error": {"slug", "code"}, "retryAfterSec"?}, no resultType
Refused WebSocket upgrade	HTTP status with the REST body; Retry-After header when throttled

The scope says who answers: SYS codes, listed below, are shared by every product, authentication and the WebSocket gateway included. Each product’s routes own their own scope, PRP for Perpetuals and OPT for Options, documented with the product:

Perpetuals Error Codes

Order creation, modification, cancellation, margin and leverage routes

Options Error Codes

Order creation, modification, cancellation and cancel-all routes

A published code is never reused.

Error Code	Error Slug	Server Status Code	Meaning
SYS-0001	UNAUTHORIZED	401	Missing, invalid or expired credentials.
SYS-0002	SERVER_ERROR	500	Internal failure. Retrying is not expected to help; the request’s effect is unknown, so look the order up.
SYS-0003	TOO_MANY_REQUESTS	429	Over a rate limit (Perpetuals, Options). Retry-After (REST) or retryAfterSec (WebSocket) says how long to wait.
SYS-0004	SERVICE_UNAVAILABLE	502, 503, 504	A dependency is down or the gateway is draining. Try again shortly.
SYS-0005	RETRYABLE_ERROR	500	A transient internal failure, such as a command that could not be queued. The request did not take effect; send it again.
SYS-0006	BAD_REQUEST	400	A malformed or invalid request field. The text names the field.
SYS-0007	NOT_FOUND	404	The order, market or resource does not exist for this account.
SYS-0008	FORBIDDEN	403	The account may not perform this action.
SYS-0009	REQUEST_TIMEOUT	408	The exchange gave up on the request internally. Its effect is unknown; look the order up before deciding what to do.
SYS-0010	DUPLICATE_REQUEST	409	The clientRequestId was already accepted within the last 60 seconds. The original request stands and is not executed a second time.
SYS-0011	SOFT_BANNED	403	Connecting is refused until the moment named in the text. See Soft Ban.
SYS-0012	SUBSCRIPTION_LIMIT	429	The connection would exceed its maximum number of stream subscriptions.
SYS-0013	CONNECTION_LIMIT	403	The account has reached its maximum number of connections to this market.
SYS-0014	TRADING_DISABLED	400	The account may not trade: it is disabled or its wallet is unverified. Returned by every order route.