# Binance API error codes: -1021, -1022, -2015 and fixes URL: https://fincodelabs.com/en/blog/binance-api-error-codes · Publisher: Fincode (Fincode Yazılım ve Teknoloji A.Ş.), Istanbul, Turkey · Category: Exchange APIs · Published: 2026-11-05 · Updated: 2026-11-05 Binance API error codes: what -1021, -1022, -2015, 429, 418 and 451 mean, what to check first, and a signing and clock check tested on the Spot Testnet. **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. 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. ```json {"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. **Common Spot API errors; meanings from the official page read 4 November 2026, checks are our own guidance** | Code | Meaning | What to check | | --- | --- | --- | | `-1003` | Too much request weight used, or IP banned | Back off; see the [rate limit guide](https://fincodelabs.com/en/blog/binance-api-rate-limit) | | `-1006`, `-1007` | Unexpected response or timeout; execution status unknown | Query the order before resending | | `-1008` | Server overloaded | Retry after a few minutes, with backoff | | `-1013` | Rejected before the matching engine, often a filter failure | The message; round to the symbol's filters | | `-1015` | Too many new orders | Order rate; order count headers | | `-1021` | Timestamp outside the recvWindow, or 1000 ms ahead | Clock sync; see below | | `-1022` | Signature not valid | The exact signed string; see below | | `-1100`, `-1102`, `-1121` | Illegal characters, missing parameter, invalid symbol | Fix the request; a retry cannot help | | `-2010` | New order rejected by the matching engine | The message, such as insufficient balance or a duplicate client order ID | | `-2011`, `-2013` | Cancel rejected; order does not exist | Symbol and order ID | | `-2014` | API key format invalid | Header present and not truncated | | `-2015` | Invalid API key, IP or permissions for action | Environment, allowlist, permissions; see below | Rounding to filters, with a worked example, is covered in the [Binance API Python guide](https://fincodelabs.com/en/blog/binance-api-python-trading-bot). ## 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. > **Hypothetical example.** With `recvWindow` at 5,000, a virtual machine whose clock is 6.2 seconds behind sends a timestamp 6,200 ms old and gets the message about being outside the recvWindow. If the clock drifts to 1.2 seconds ahead, the timestamp is 1,200 ms in the future and the message says it was 1000ms ahead. A larger window would hide the first case and do nothing for the second. 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. ```python 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](https://fincodelabs.com/en/blog/exchange-api-key-how-to), and a start-up check that refuses an over-permissioned key is in [API key security for trading bots](https://fincodelabs.com/en/blog/api-key-security-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](https://fincodelabs.com/en/blog/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)](https://developers.binance.com/en/docs/products/spot/errors) - [Binance Spot API documentation: Error codes (GitHub)](https://github.com/binance/binance-spot-api-docs/blob/master/errors.md) - [Binance USD-M Futures: Error codes (last modified 30 October 2026)](https://developers.binance.com/en/docs/products/derivatives-trading-usds-futures/error-code) - [Binance Spot API documentation: REST API (HTTP return codes, timing security, signed examples)](https://github.com/binance/binance-spot-api-docs/blob/master/rest-api.md) - [Binance Spot API documentation: WebSocket API (signatures, session errors)](https://github.com/binance/binance-spot-api-docs/blob/master/web-socket-api.md) - [Binance Spot API CHANGELOG (percent-encoding notice of 2025-12-17, -1131)](https://github.com/binance/binance-spot-api-docs/blob/master/CHANGELOG.md) - [Binance Spot Testnet: General info](https://github.com/binance/binance-spot-api-docs/blob/master/testnet/general-info.md) - [Binance Support: How to Create API Keys on Binance (updated 20 March 2025)](https://www.binance.com/en/support/faq/detail/360002502072) - [RFC 7725: An HTTP Status Code to Report Legal Obstacles](https://www.rfc-editor.org/rfc/rfc7725.html) - [Capital Markets Law No. 6362, Article 99/A (Turkish, consolidated text)](https://www.mevzuat.gov.tr/mevzuatmetin/1.5.6362.pdf) - [SPK: Announcement on crypto-asset service providers, 5 August 2024 (Turkish)](https://spk.gov.tr/duyurular/basin-duyurulari/2024/kripto-varlik-hizmet-saglayicilara-iliskin-duyuru_05082024) > 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](https://fincodelabs.com/en/editorial-policy). --- Published by Fincode (Fincode Yazılım ve Teknoloji A.Ş.), a software company in Istanbul, Turkey: https://fincodelabs.com/en/blog/binance-api-error-codes Cite as: Fincode, "Binance API error codes: -1021, -1022, -2015 and fixes", updated November 5, 2026, https://fincodelabs.com/en/blog/binance-api-error-codes