Binance API error codes: -1021, -1022, -2015 and fixes

Short answer: Binance API error codes are negative numbers returned with a message in a JSON body, where 10xx covers server and network issues, 11xx request problems and 20xx mostly order and key rejections. Three that commonly stop an integration are -1021 (timestamp outside the recvWindow), -1022 (signature not valid) and -2015 (invalid API key, IP or permissions). Check the clock first, then the exact string you signed, then the key's environment, IP allowlist and permissions.

Debug a rejected signature with a sample or testnet key, or a timestamp outside recvWindow: HMAC signature generator and Unix timestamp converter.

A numbered error usually means an integration has stopped and someone needs the cause now, so this guide starts with a table of what to check, then takes three common errors in detail. Meanings come from Binance's official error page, last modified 30 October 2026, read on 4 November 2026. Where possible, each error was reproduced that day on the public Spot Testnet using placeholder values, never a real key.

This guide describes the documentation and does not recommend Binance or any strategy; automated trading can lose money. Availability depends on your jurisdiction and the platform's terms. In Turkey, Article 99/A of Capital Markets Law No. 6362 treats activity by foreign-based crypto-asset platforms directed at Turkish residents as unauthorized service provision, and the Capital Markets Board (SPK) has stated that appearing on its list of operating providers does not mean a firm is authorized.

Binance API error format: code, message and HTTP status

A Binance error is a JSON body holding a negative code and a message, sent with an HTTP status that tells you whose side the problem is on.

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

Binance says codes are universal but messages can vary, so program logic should branch on the code. HTTP 4XX means a malformed request from the sender; 5XX means an internal error on Binance's side. Public testnet requests on 4 November 2026 returned HTTP 400 with -1121 for symbol NOPE, -1120 for interval 9x, -1102 for depth with no symbol and -1101 for an extra parameter on time. A signed call with recvWindow=70000 returned -1131, a code that is not on the current error page and appears only in the changelog. So treat the published list as incomplete: log unknown codes with the full message and stop that action rather than retrying.

Binance API error codes: what each one means and what to check

Most codes point to one thing to check, and only a few are worth retrying without changing the request.

Rounding to filters, with a worked example, is covered in the Binance API Python guide.

Binance API error 1021: timestamp outside the recvWindow

Error -1021 means the timestamp on a signed request failed the server's timing check, almost always because of the sending machine's clock or a delay before sending.

The Spot REST documentation gives the rule: the request proceeds only if the timestamp is less than server time plus 1 second and server time minus the timestamp is at most recvWindow. recvWindow defaults to 5,000 ms and has a maximum of 60,000 ms, and Binance recommends 5,000 or less. The tolerance is lopsided: at the default, a clock may run almost 5 seconds behind but less than 1 second ahead.

Check time synchronization on the host first, then the offset against GET /api/v3/time. Next, look at where the timestamp is created: build it immediately before sending, not when a job enters a queue, and rebuild timestamp and signature on every retry. Change the window last, because raising it treats the symptom and lengthens the time a captured request stays valid.

Binance API signature for this request is not valid: error 1022

Error -1022 means the server computed a different signature from yours, so the string you signed is not the string it received, or the key is the wrong one.

• Payload changed after signing. An HTTP library re-encoded or reordered parameters. Build the query string yourself, sign that exact string and send it unchanged.
• Percent-encoding order. The changelog entry of 17 December 2025 announced that from about 15 January 2026 REST payloads must be percent-encoded before signing. It matters for any value that changes when encoded, such as a non-ASCII symbol name.
• Query string plus body. The signature payload is the query string joined to the HTTP body with no separator.
• WebSocket API rules differ. Its signature is computed over parameters sorted by name.
• Key type mix-up. HMAC produces hex; RSA and Ed25519 produce base64, whose special characters must be percent-encoded in a query string. RSA and Ed25519 signatures are case-sensitive; HMAC signatures are not.
• Wrong secret. A stray newline when loading it, or a testnet secret on production.

A placeholder key cannot reach -1022, because an unknown key stops at -2015 first, so test signing code offline against a known answer.

A tested signing and clock check on the Spot Testnet

This script needs no account: it measures clock offset, reproduces the signing examples published in Binance's documentation and shows how the testnet orders its checks.

import hashlib, hmac, time, urllib.parse
import requests

BASE = "https://testnet.binance.vision"      # Spot Testnet, placeholders only

# 1. Clock: server time against local time, allowing for the round trip
t0 = time.time()
server_ms = requests.get(BASE + "/api/v3/time", timeout=10).json()["serverTime"]
local_ms = (t0 + time.time()) / 2 * 1000
print("clock offset ms:", round(server_ms - local_ms))

# 2. Signature: reproduce the worked examples in Binance's REST documentation.
#    The secret is the sample published there, not a real key.
SECRET = b"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"

def sign(payload):
    return hmac.new(SECRET, payload.encode(), hashlib.sha256).hexdigest()

params = dict(symbol="LTCBTC", side="BUY", type="LIMIT", timeInForce="GTC", quantity="1",
              price="0.1", recvWindow="5000", timestamp="1499827319559")
print(sign(urllib.parse.urlencode(params)).startswith("c8db5682"))

params["symbol"] = "１２３４５６"            # the docs' non-ASCII symbol
print(sign(urllib.parse.urlencode(params)).startswith("e1353ec6"))   # percent-encoded first
raw = "&".join(f"{k}={v}" for k, v in params.items())
print(sign(raw).startswith("e1353ec6"))                              # would earn -1022

# 3. Key and timestamp: what the server checks, in order, with placeholders
def account(key, age_ms=0):
    q = {"timestamp": int(time.time() * 1000) - age_ms, "signature": "0" * 64}
    r = requests.get(BASE + "/api/v3/account", params=q,
                     headers={"X-MBX-APIKEY": key}, timeout=10)
    return r.status_code, r.json()["code"]

print(account("not-a-key"))                  # malformed key
print(account("not-a-key", age_ms=600_000))  # malformed, ten minutes old
print(account("A" * 64))                     # well formed, unknown
print(account("A" * 64, age_ms=600_000))     # ten minutes old
print(account("A" * 64, age_ms=-600_000))    # ten minutes ahead

Output on 4 November 2026 (Python 3.11, requests):

clock offset ms: 2061
True
True
False
(401, -2014)
(400, -1021)
(401, -2015)
(400, -1021)
(400, -1021)

The test machine was about 2 seconds behind server time, which passes at the default window but uses up 2 of its 5 seconds. The signature lines show a signer matching both published answers, then failing when a non-ASCII value is signed without percent-encoding. The last five lines show that, with a current timestamp, a malformed key returns -2014 and a well-formed unknown key -2015, while a timestamp outside the window returned -1021 whichever key was sent. The timestamp was checked first, so a -1021 says nothing about whether your key is valid.

Binance API error 2015: invalid API key, IP or permissions

Error -2015 is one message for several causes, so work through the key's environment, its IP allowlist and its permissions in turn.

• Wrong environment. Spot Testnet keys are separate from production keys, and a key sent to the other host looks unknown. A well-formed placeholder returned HTTP 401 with -2015 in our test.
• IP. The request's outbound address must be on the key's allowlist. Check what the server actually uses, including NAT gateways and new deployments.
• Permissions. The REST documentation says a key cannot trade until trading is enabled. Binance's support page, last updated 20 March 2025, adds that, under its default security controls, a system-generated HMAC key without an IP restriction can only be set to read.
• Product. The same page says keys created before you enable Futures cannot enable that permission, so a working Spot key can still fail on futures endpoints.
• Revoked during a session. On the WebSocket API, if a logged-on key becomes invalid, the next request ends the session with status 401 and -2015.

-2014 is simpler: the key format is wrong, and the testnet also returned it when the X-MBX-APIKEY header was missing. Creating a key with the right settings is covered in how to create an exchange API key, and a start-up check that refuses an over-permissioned key is in API key security for trading bots.

Binance API error 418, 429, 403 and 451

Errors 418, 429, 403 and 451 are HTTP statuses rather than Binance error codes, and none of them is fixed by resending the request.

• 429 means a request rate limit was broken, and 418 means the IP was auto-banned for continuing afterward. Wait for Retry-After; the mechanics are in the rate limit guide linked above.
• 403 means a Web Application Firewall rule was violated, which can indicate a rate limit violation or a security block. The documentation also warns that SQL keywords in requests may trigger such a block.
• 451 is the standard status for access denied as a consequence of a legal demand (RFC 7725). Binance's Spot error page does not list it, as read on 4 November 2026. If you receive it, the service is not available from that location. That is not a code problem, and there is nothing to fix in the integration.

HTTP 5XX, -1006 and -1007: the order status is unknown

After a 5XX, -1006 or -1007 response, the request may have succeeded, so find out before you send it again.

The Spot documentation says APIs time out after 10 seconds waiting for the matching engine, that this does not always mean the request failed, and that 5XX must not be treated as a failed operation. Check the user data stream for the event, then query the order by its client order ID. If it is not there, wait and check again; if it is still missing, stop and reconcile rather than resend automatically. Retry and backoff patterns are in crypto exchange API integration.

Frequently asked questions

Should I increase recvWindow to fix -1021?

Only after fixing the clock. Binance recommends 5,000 ms or less, the maximum is 60,000 ms, and a larger window does not help when the timestamp is ahead of server time.

What does Invalid API-key, IP, or permissions for action mean?

It is error -2015. The key may belong to another environment, the request may come from an address not on the allowlist, or the key may lack the permission the endpoint needs.

What does Binance API error 451 mean?

HTTP 451 is the standard status for access denied because of a legal demand, and it means the service is not available from that location. It cannot be fixed in code.

Which Binance errors are safe to retry?

Retry -1008 and rate limit responses after waiting. After 5XX, -1006 or -1007, check the order first. Errors such as -1021, -1022, -2015 and -1121 need a fix, not a retry.

Where is the official list of Binance API error codes?

On the Spot error codes page of Binance's developer documentation, also published in its GitHub repository. USD-M futures has its own error code page.

Sources

• Binance Developer Docs: Spot error codes (last modified 30 October 2026) (opens in a new tab)
• Binance Spot API documentation: Error codes (GitHub) (opens in a new tab)
• Binance USD-M Futures: Error codes (last modified 30 October 2026) (opens in a new tab)
• Binance Spot API documentation: REST API (HTTP return codes, timing security, signed examples) (opens in a new tab)
• Binance Spot API documentation: WebSocket API (signatures, session errors) (opens in a new tab)
• Binance Spot API CHANGELOG (percent-encoding notice of 2025-12-17, -1131) (opens in a new tab)
• Binance Spot Testnet: General info (opens in a new tab)
• Binance Support: How to Create API Keys on Binance (updated 20 March 2025) (opens in a new tab)
• RFC 7725: An HTTP Status Code to Report Legal Obstacles (opens in a new tab)
• Capital Markets Law No. 6362, Article 99/A (Turkish, consolidated text) (opens in a new tab)
• SPK: Announcement on crypto-asset service providers, 5 August 2024 (Turkish) (opens in a new tab)

This guide is general information about software and markets, not investment, legal or tax advice. Automated trading can lose money, past or backtested performance does not guarantee future results, and the rules that apply depend on your jurisdiction and your exchange's terms. Sources, checks and corrections: see the editorial policy.