Error Codes

Endpoint Error Codes (/fapi)

When a /fapi endpoint rejects a request, the response body has the following structure:

{
  "code": -1121,
  "msg": "Invalid symbol: XYZUSDT"
}

Most errors are returned with HTTP status 400; -2013 (order not found) may be returned with 404, and -1000/-1001 (internal errors) with 500.

The following codes are in use:

10xx — General Issues

Error Code	Error Name	Description / Reason
-1000	UNKNOWN	An unknown error occurred while processing the request (e.g. an internal storage error).
-1001	DISCONNECTED	Internal error; unable to process the request. Please retry.
-1013	FILTER_FAILURE	Order rejected by a symbol filter. The message names the failed filter: Filter failure: LOT_SIZE (quantity below or rounding below the minimum lot size), Filter failure: MIN_NOTIONAL (order notional below the symbol minimum; reduce-only orders are exempt), or Filter failure: MAX_NOTIONAL (order notional above the symbol maximum). Filter values are published per symbol in the filters array of GET /fapi/v1/exchangeInfo.

11xx — Request Parameter Issues

Error Code	Error Name	Description / Reason
-1100	ILLEGAL_CHARS / BAD_VALUE	A parameter value is malformed: invalid quantity, price, stopPrice, orderId, or goodTillDate; non-positive numeric value; newClientOrderId longer than 36 chars or containing illegal characters; query window exceeding 7 days.
-1102	MANDATORY_PARAM_EMPTY_OR_MALFORMED	A mandatory parameter was not sent: e.g. quantity, price for LIMIT orders, orderId/origClientOrderId on cancel/query, goodTillDate when timeInForce=GTD. Also returned when timeInForce=GTD is sent on a regular (non-algo) order, which is not supported.
-1106	PARAM_NOT_REQUIRED	A parameter was sent that is not required or conflicts with another: closePosition together with reduceOnly or quantity, or closePosition on an order type other than STOP_MARKET / TAKE_PROFIT_MARKET.
-1120	BAD_INTERVAL	Invalid kline interval or statistics period.
-1121	BAD_SYMBOL	Invalid or unknown trading pair.
-1125	INVALID_LISTEN_KEY	This listenKey does not exist (expired or never created). Re-issue via POST /fapi/v1/listenKey.
-1128	OPTIONAL_PARAMS_BAD_COMBO	Invalid combination or value of optional parameters, e.g. a marginType other than CROSSED / ISOLATED.
-1130	INVALID_PARAMETER	Invalid data sent for a parameter: unknown side, type, algoType, or a positionSide other than BOTH.

20xx — Order Processing Issues

Error Code	Error Name	Description / Reason
-2010	NEW_ORDER_REJECTED	New order rejected, e.g. a GTX (post-only) order that would immediately match and take.
-2011	CANCEL_REJECTED	Cancel rejected: unknown order sent, or the order is already in a terminal state.
-2013	NO_SUCH_ORDER	Order does not exist (or cannot be modified).
-2014	DUPLICATE_CLIENT_ORDER_ID	Duplicate newClientOrderId — another active order already uses this id.
-2019	MARGIN_NOT_SUFFICIENT	Insufficient available balance for the required margin.
-2021	ORDER_WOULD_IMMEDIATELY_TRIGGER	Conditional order would be triggered immediately at the current mark price.
-2022	REDUCE_ONLY_REJECT	Reduce-only order rejected: no opposite-side position to reduce.

40xx — Account Configuration Issues

Error Code	Error Name	Description / Reason
-4028	INVALID_LEVERAGE	Leverage is not valid: below 1 or above the symbol's maximum leverage.
-4046	MARGIN_TYPE_NOT_SUPPORTED	Isolated margin is not supported — the exchange runs in cross-margin mode only.
-4059	POSITION_MODE_NOT_SUPPORTED	Hedge mode (dualSidePosition=true) is not supported — the exchange runs in one-way position mode only.

Authentication Errors

Authentication failures do not use the {code, msg} format above. They are rejected by the authentication middleware before the endpoint runs, with an HTTP 401 (or 403) status and the standard API response envelope:

{
  "success": false,
  "data": null,
  "error": {
    "code": "SIGNATURE_INVALID",
    "message": "Timestamp outside recv window"
  },
  "timestamp": 1711000000
}

HTTP Status	Error Code	Reason
401	SIGNATURE_INVALID	HMAC signature verification failed: missing signature or timestamp parameter, invalid signature, or timestamp outside the fixed ±60,000 ms window relative to server time.
401	INVALID_API_KEY	The X-MBX-APIKEY header does not match any known API key.
401	API_KEY_DISABLED	The API key exists but is disabled.
403	IP_NOT_ALLOWED	The client IP is not in the API key's IP whitelist.

Note: timestamp and signature problems return 401 SIGNATURE_INVALID as shown above — there are no -1021 / -1022 style codes on this API.