Error Codes

Three error envelopes exist. Pick the one that matches the surface you are calling.

FAPI business errors (Binance envelope)

HTTP/1.1 400 Bad Request
content-type: application/json

{ "code": -2019, "msg": "Margin is insufficient." }

Code	HTTP	Name	When
-1000	500	UNKNOWN	Uncategorised error (e.g. DB failure on fundingFeeHistory)
-1001	500	DISCONNECTED	Internal service error / shard forwarding failed
-1003	429	TOO_MANY_REQUESTS	A request-weight or order-count ceiling was exceeded; see Rate limits. Headers carry the current counts
-1013	400	INVALID_QUANTITY	quantity < lot_size, or notional outside [min_order_size_usd, max_order_size_usd]
-1021	400	INVALID_TIMESTAMP	timestamp outside the ±60 s window
-1100	400	ILLEGAL_CHARS	Unparseable UUID / quantity / price; bad clientOrderId characters; algo window > 7 days
-1102	400	MANDATORY_PARAM_EMPTY_OR_MALFORMED	Missing required parameter; side mismatch on modify; unsupported timeInForce; bad batchOrders
-1106	400	PARAMETER_NOT_REQUIRED	quantity + quoteOrderQty together; closePosition conflicts
-1120	400	INVALID_INTERVAL	Bad kline interval / futures-data period
-1121	400	INVALID_SYMBOL	Symbol not in this deployment's market config
-1125	404	INVALID_LISTEN_KEY	No active listenKey on PUT /fapi/v1/listenKey
-1130	400	INVALID_DATA_FOR_PARAMETER	Unrecognised side / type / algoType / positionSide
-2010	400	NEW_ORDER_REJECTED	GTX would match immediately; OI cap exceeded; trigger-order limit reached
-2011	400	UNKNOWN_ORDER	Engine does not hold the order on cancel/modify (never faked as CANCELED)
-2013	404	NO_SUCH_ORDER	Order does not exist / cannot be modified / not open
-2014	400	API_KEY_FORMAT (reused)	Duplicate newClientOrderId among active orders
-2019	400	MARGIN_INSUFFICIENT	Not enough available balance to freeze margin
-2021	400	ORDER_WOULD_TRIGGER_IMMEDIATELY	Trigger condition already satisfied
-2022	400	REDUCEONLY_REJECT	reduceOnly with no opposite-side position
-4028	400	INVALID_LEVERAGE	Leverage outside [1, market max]
-4046	400	NO_NEED_TO_CHANGE_MARGIN_TYPE (reused)	marginType=ISOLATED on FAPI
-4059	400	NO_NEED_TO_CHANGE_POSITION_SIDE (reused)	dualSidePosition=true

FAPI authentication errors (Sparky envelope)

Key and signature failures come from the auth middleware and use Sparky's ApiResponse envelope, not the Binance one. Most clients only need the HTTP status.

HTTP/1.1 401 Unauthorized
content-type: application/json

{ "success": false, "data": null, "error": { "code": "SIGNATURE_INVALID", "message": "..." }, "timestamp": 1714261234 }

error.code	HTTP	When
INVALID_API_KEY	401	X-MBX-APIKEY not found on this deployment
API_KEY_DISABLED	401	Key status != active
IP_NOT_ALLOWED	403	Client IP not in the key's whitelist
SIGNATURE_INVALID	401	HMAC mismatch, missing timestamp, or timestamp outside the window

Native API errors (/api/v1/*)

{ "error": "Insufficient available balance", "code": "INSUFFICIENT_BALANCE" }

Some handlers use the { "success": false, "error": { "code", "message" } } envelope instead; check the status code first.

Code	Meaning
INVALID_ADDRESS	Wallet address malformed
TIMESTAMP_EXPIRED	Login / EIP-712 timestamp outside ±5 min
USER_NOT_FOUND	Call the nonce endpoint first
SIGNATURE_INVALID, SIGNATURE_FORMAT_INVALID	EIP-712 signature failed / not 0x-prefixed
INVALID_TOKEN	JWT missing / expired
LIMIT_REACHED, INVALID_IP	API-key creation limits
INVALID_SYMBOL, INVALID_LEVERAGE, INVALID_AMOUNT, PRICE_REQUIRED	Order validation
SLIPPAGE_EXCEEDED	Market order simulated slippage above max_slippage
INSUFFICIENT_BALANCE	Available balance too low
OI_CAP_EXCEEDED	Order would exceed the market's per-side OI cap (current, cap, requested_delta in the message)
ORDER_NOT_FOUND, ORDER_NOT_OWNED, ORDER_NOT_CANCELLABLE	Order lookup / cancel
HAS_OPEN_ORDERS, HAS_OPEN_POSITIONS, INVALID_MARGIN_MODE	Margin-mode switch preconditions
INVALID_MARKET, ERR_INVALID_PERIOD, ERR_NO_DATA, CIRCUIT_OPEN, PRICE_DATA_UNAVAILABLE	Market-data endpoints

Referral error codes are listed on the Referral overview.

Common pitfalls

• SIGNATURE_INVALID on POST/PUT only — you signed the query string but did not append the raw JSON body (or you URL-encoded the body). See Signing.
• -1021 — check GET /fapi/v1/time; the window is 60 s and recvWindow cannot widen it. Timestamps in the future fail too.
• INVALID_API_KEY on a key that works elsewhere — keys are per chain; you are talking to a different deployment.
• -2011 on cancel — the order was already filled/cancelled. Treat as done, then reconcile with GET /fapi/v1/order.
• -1013 from a float tail — quantities that are not lot multiples are floored, but anything below one lot is rejected; round before sending.