Error Codes

---

HTTP Status Codes

All API responses return a standard HTTP status code. Treat any non-200 response as an error.

Code	Meaning	What to do
200	Success	Parse the response body for your data
400	Bad Request — invalid or missing parameters	Check request params against the endpoint spec
401	Unauthorized — missing or invalid credentials	Verify API key, nonce freshness, and signature
403	Forbidden — insufficient permission	Check your API key has the required permission level
404	Not Found — resource does not exist	Verify the endpoint path and any IDs
405	Method Not Allowed — wrong HTTP method	Use the correct method (GET/POST/PUT/DELETE)
408	Request Timeout — exceeded 30 seconds	Retry once; if persistent, check server status
429	Too Many Requests — rate limit exceeded	Back off and retry after Retry-After header value
451	Unavailable For Legal Reasons — account banned	Contact support
500	Internal Server Error	Retry with backoff; report if persistent

Error Response Format

Non-200 responses return a JSON body:

{
  "status": 400,
  "error": "Bad Request",
  "code": 301,
  "message": "Invalid order size"
}

Field	Description
status	HTTP status code
error	HTTP status text
code	Internal error code (see API Status Enum below)
message	Human-readable error description

Handling 429 (Rate Limit)

When rate-limited, the response includes a Retry-After header indicating the number of seconds to wait before retrying (RFC 7231 §7.1.3):

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Strategy: Parse the Retry-After value as an integer number of seconds, wait that long, then resume. Standard HTTP client libraries (urllib3.Retry, axios-retry, OkHttp) handle this automatically. Do not retry immediately — repeated violations trigger escalating blocks (1s → 5min → 15min). See Authentication → Rate Limits.

Handling 401 (Unauthorized)

Common causes:

• Wrong nonce — the nonce must be the current UTC time in milliseconds. Clock drift > a few seconds causes rejection.
• Wrong signature — the signing input is path + nonce + body with no separators. Verify the concatenation.
• Body mismatch — the body you sign must be identical to the body you send. Watch for JSON key ordering if your language reorders keys.

---

Common Error Strings → Likely Cause

The error message field is often opaque on its own. Use this table to map the literal string the API returned to the most common root cause, ordered by frequency.

Error string in response	Status	Most likely cause	What to check first
api parameter is mandatory	401	Wrong header names. The required headers are request-api, request-nonce, request-sign — not X-BTSE-APIKEY, BTSE-API-KEY, etc.	Header names match the Authentication spec exactly, lowercase, hyphen-separated.
Authentication Failed (code 10002)	401	Signature payload mismatch. The string you hashed is not what the server reconstructed.	The signed urlpath excludes any query string; the body you signed is byte-identical to the body sent. See the Signed Request Walkthrough.
Signature verification failed	401	Same as above — query string included in the signed urlpath, or body re-serialized between signing and sending.	Print the exact bytes passed to HMAC, compare with the spec.
Invalid nonce / nonce reuse	401	Clock drift or reused nonce. Nonce must be current UTC in milliseconds, monotonically increasing per API key.	Use time.time() * 1000 (Python) / Date.now() (JS). NTP-sync your machine if drift > a few seconds.
Invalid request parameters (code -2)	400	Unknown symbol, malformed walletName, missing required param.	Diff your request against the endpoint's spec page.
Invalid order size (code 301)	400	Size below the symbol's minimum or above the maximum.	Check minOrderSize / maxOrderSize from /api/v3.3/market_summary (Spot) or the Futures market info endpoint.
Invalid order price (code 302)	400	Price outside the contract's tick-size grid, or price filter (PRICE_FILTER).	Round price to the symbol's tick size before submitting.
Maximum open orders exceeded (code 304)	400	Per-user or per-symbol open-order limit reached.	Cancel stale orders or use cancelAllAfter (dead-man's switch).
Order not found (code 16)	404	The orderID / clOrderID doesn't match any active or recent order.	Verify the ID. After 24h cancelled/filled orders may no longer be queryable by ID — use trade-history endpoints instead.
Insufficient balance (code 8)	400	Wallet balance below required amount including fees.	Check available (not total) balance, account for fees and any open orders that already reserve funds.
Rate limit exceeded (code 303)	429	API rate limit tier triggered.	See Authentication → Rate Limits. Back off using Retry-After.
Account is undergoing liquidation (code 64)	400	Futures account in liquidation — new orders blocked.	Wait for liquidation to complete; query position status.
Order is undergoing auto-deleveraging (code 1004)	400	Position selected for ADL — cannot amend/cancel.	Position will be force-reduced; monitor via WebSocket notifications.

Tip for AI/agent integrations: when you encounter an error string that isn't in this table, paste the literal message field into a search of this file before assuming it's a new bug. Most "weird" BTSE errors are one of the rows above, surfaced with slightly different wording.

---

API Status Enum

Internal numeric status codes appear in order and WebSocket response payloads.

Code	Constant	Description
-2	INVALID_REQUEST	Invalid request parameters (e.g. unknown symbol, malformed walletName)
-1	TIMEOUT	Request timed out — verify order status separately
1	MARKET_UNAVAILABLE	Futures market is unavailable
2	ORDER_INSERTED	Order inserted successfully
4	ORDER_FULLY_TRANSACTED	Order fully filled
5	ORDER_PARTIALLY_TRANSACTED	Order partially filled
6	ORDER_CANCELLED	Order cancelled successfully
7	ORDER_REFUNDED	Order refunded
8	INSUFFICIENT_BALANCE	Insufficient account balance
9	TRIGGER_INSERTED	Trigger order inserted successfully
10	TRIGGER_ACTIVATED	Trigger order activated
11	ERROR_INVALID_CURRENCY	Invalid currency specified
12	ERROR_UPDATE_RISK_LIMIT	Error updating risk limit
13	ERROR_INVALID_LEVERAGE	Invalid leverage value
15	ORDER_REJECTED	Order rejected
16	ORDER_NOTFOUND	Order not found by the provided orderID or clOrderID
17	REQUEST_FAILED	Request failed — verify order status
20	SUCCESS	Action completed successfully
21	FREEZE_SUCCESSFUL	Freeze action succeeded
27	TRANSFER_SUCCESSFUL	Funds transferred between futures and spot successfully
28	TRANSFER_UNSUCCESSFUL	Transfer between spot and futures failed
29	QUERY_GET_ORDERS	Response to a get-orders query
31	QUERY_GET_POSITIONS	Response to a get-positions query
33	QUERY_GET_ALL_POSITIONS_ORDERS	Response to a get-all-positions-orders query
34	QUERY_WALLET	Response to a wallet query
36	QUERY_FUTURES_MARGIN	Response to a futures-margin query
41	ERROR_INVALID_RISK_LIMIT	Invalid risk limit specified
51	QUERY_GET_ORDERS_WITH_LIMIT	Response to a paginated get-orders query (with limit)
64	STATUS_LIQUIDATION	Account is undergoing liquidation
65	STATUS_ACTIVE	Order is active
66	MODE_BUY	Buy side
76	ORDER_TYPE_LIMIT	Limit order
77	ORDER_TYPE_MARKET	Market order
80	ORDER_TYPE_PEG	Peg / Algo order
81	ORDER_TYPE_OTC	OTC order
83	MODE_SELL	Sell side
85	STATUS_PROCESSING	Order is processing
88	STATUS_INACTIVE	Order is inactive
101	FUTURES_ORDER_PRICE_OUTSIDE_LIQUIDATION_PRICE	Futures order price is outside liquidation price
110	FUTURES_FUNDING	Futures funding event
123	AMEND_ORDER	Order amended successfully
124	UNFREEZE_SUCCESSFUL	Unfreeze action succeeded
300	ERROR_MAX_ORDER_SIZE_EXCEEDED	Order size exceeds the maximum allowed
301	ERROR_INVALID_ORDER_SIZE	Invalid order size
302	ERROR_INVALID_ORDER_PRICE	Invalid order price
303	ERROR_RATE_LIMITS_EXCEEDED	Rate limit exceeded
304	ERROR_MAX_OPEN_ORDER_EXCEEDED	Maximum open orders exceeded
1003	ORDER_LIQUIDATION	Order is undergoing liquidation
1004	ORDER_ADL	Order is undergoing auto-deleveraging (ADL)
30410	BLOCK_TRADE_COMPLETE_SUCCESS	Block trade completed successfully