Error Codes

Complete error code reference for WebSocket and REST APIs

Error Response Format

WebSocket

{
  "type": "error",
  "code": 4001,
  "message": "Signature verification failed"
}

REST API

{
  "error": "Signature verification failed"
}

REST API errors return standard HTTP status codes (400, 403, 404, 500, 503) with error message in response body.

---

Error Codes

Authentication Errors (4000-4019)

Code	Error	Description
4000	INVALID_REQUEST	Malformed request or missing required fields
4001	INVALID_SIGNATURE	Signature verification failed
4002	INVALID_NONCE	Nonce validation failed (expired, replay, or out of window)
4003	NOT_AUTHENTICATED	Connection not authenticated
4004	WALLET_MISMATCH	Signed wallet doesn't match authenticated wallet
4015	USER_NOT_INVITED	Wallet has not been granted app access. Apply a referral code via POST /api/referral/apply.

Validation Errors (4020-4049)

Code	Error	Description
4029	RATE_LIMIT_EXCEEDED	Request rate limit exceeded (20 req/s per authenticated wallet)
4030	INVALID_ORDER_TYPE	Invalid order type
4031	INVALID_TIME_IN_FORCE	Invalid time in force value
4032	INVALID_ORDER_PRICE	Invalid or missing price for order type
4033	ALREADY_SUBSCRIBED	Connection already subscribed to trading stream
4034	INVALID_ORDER_QUANTITY	Invalid order quantity
4035	SUSTAINED_RATE_LIMIT_EXCEEDED	Signed request budget exhausted (see Nonce & Rate Limits)
4040	ACCOUNT_NOT_FOUND	Trading account not found
4041	ORDER_NOT_FOUND	Cancel/replace target already filled, cancelled, or expired — benign race, safe to ignore

Business Logic Errors (4100-4199)

Code	Error	Description
4100	INSUFFICIENT_MARGIN	Insufficient margin for operation
4101	ORDER_TOO_SMALL	Order notional size below minimum ($5)
4102	MAX_LEVERAGE_EXCEEDED	Leverage exceeds instrument maximum
4103	OI_CAP_EXCEEDED	Order would exceed open interest cap

Server Errors (5000-5099)

Code	Error	Description
5000	INTERNAL_ERROR	Internal server error
5001	EXCHANGE_ERROR	Exchange matching engine error
5002	LEDGER_UNAVAILABLE	Risk engine unavailable
5003	EXCHANGE_ACCOUNT_ERROR	Account creation or retrieval failed

---

---

HTTP Status Codes

Status	Description	Typical Cause
200	Success	Request completed successfully
400	Bad Request	Invalid parameters or signature validation failed
403	Forbidden	Wallet not invited. Body starts with USER_NOT_INVITED: — apply a referral code via POST /api/referral/apply.
404	Not Found	Resource does not exist
500	Internal Server Error	Server-side error
503	Service Unavailable	Transient — auth-service unreachable, safe to retry

---

Error Handling

Retryable Errors

Code	Retry Strategy
5000	Retry with exponential backoff
5002	Retry after delay (service may be unavailable)
503	Retry after delay

Non-Retryable Errors

Code	Required Action
4001	Fix signature generation
4002	Generate fresh nonce
4041	None — order already gone; do not retry
4100	Deposit margin or reduce position size
4101	Increase order quantity
4102	Reduce leverage or position size
4103	Reduce order size

Rate Limit Handling

When receiving error code 4029:

• Stop sending requests immediately

• Wait for rate limit window to reset (1 second)

• Implement exponential backoff for subsequent requests

When receiving error code 4035 (sustained budget exhausted):

• Reduce your sustained request rate — the budget frees as older signed requests age past the 5-minute nonce window

• Cancels are granted 2x budget headroom and keep working, so always prefer cancelling resting orders over waiting