Binance API error -2014: API-key format invalid
Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs.
Binance error -2014 is BAD_API_KEY_FMT, and the official error list says
only this: “API-key format invalid.” That sentence is the entire official
explanation. We did not find an official list of causes, so everything below it
on this page is inference from how the key travels — labelled as such.
The good news is that the inference is short. The key goes to Binance in one
place, the X-MBX-APIKEY header, and -2014 says the value in that header is
not shaped like a key. So the question is not “what is wrong with my account”
but “what string did my code actually put in that header”.
What this error actually means
The name and the message both point at format, not validity. The distinction matters because Binance has a separate code for a key that is well-formed and then refused:
| Code | Name | Official message | What it points at |
|---|---|---|---|
-2014 | BAD_API_KEY_FMT | “API-key format invalid.” | The string in the header |
-2015 | REJECTED_MBX_KEY | “Invalid API-key, IP, or permissions for action.” | The key itself, the calling IP, or a permission |
-1022 | INVALID_SIGNATURE | “Signature for this request is not valid.” | The signature computed with the secret |
If you have -2014, the dashboard settings — permissions, IP whitelist, the
90-day trading expiry — are not your problem yet. Those are
-2015 territory. -2014 is documented with
the same code and message for Spot and for USDⓈ-M futures.
The usual cause: invisible characters
In practice, the header carries something the key does not: characters you cannot see in a log line or a terminal.
- A trailing newline from reading the key out of a file.
- A carriage return from a
.envfile saved with Windows line endings. The key looks right everywhere except on the wire. - Leading or trailing spaces picked up when copying the key from a web page.
- Surrounding quotes from an env file whose loader does not strip them, so
the header value is literally
"abc…"including the quote marks.
All four are fixed the same way: normalise at load, and refuse to start if the value still looks wrong.
key = os.environ["BINANCE_API_KEY"]
if key != key.strip() or key[:1] in ("'", '"'):
raise SystemExit("BINANCE_API_KEY has surrounding whitespace or quotes")Failing at startup turns a confusing runtime error into a one-line configuration message.
Other causes, in order of likelihood
All of these are inference; Binance does not enumerate them.
1. The wrong value in the header. Two variables swapped, so the secret goes in the header and the key goes into the signing function. With self-generated RSA or Ed25519 keys there are more strings in play — the private key, the public key you registered, and the API key Binance associates with it — and only the API key belongs in the header. Sending a PEM block there is a format error by any reading.
2. A truncated key. Copied short from the interface, cut by a line wrap in a config file, or clipped by a secrets store or CI variable with a length limit.
3. An empty or unset variable. The environment variable was never set in
this environment — a container, a CI job, a service manager with its own
environment — so the header is empty. We did not find documentation of which
code Binance returns for an empty or missing header; -2014 is plausible, but do
not rely on it to tell you the variable is unset. Check for that explicitly.
4. A placeholder left in. your_api_key_here from a template, or a value
from an example config that was never replaced.
5. Lookalike characters. A key pasted through a chat app, a document editor or a password manager note can pick up characters that render identically but are different bytes.
How to confirm which one you have
You need to see the value your code sends without writing the key into a log. Log its shape instead:
| Check | How | What it tells you |
|---|---|---|
| Length | len(key) compared with the key as shown when you created it | Truncation, or extra characters |
| Edges | First and last four characters, plus repr() of the last one | Newlines, carriage returns, quotes |
| Source | Which variable, file or secret feeds the header | Swapped values, the wrong environment |
| Empty | Whether the value is empty or unset at the point of the request | Missing configuration |
| Outside your code | The same key in a minimal request from another tool | Whether the bug is in your loading path |
The last check is the fastest discriminator. If the key works from a minimal request and fails from your application, the key is fine and your loading path is not. Regenerating the key will not help in that case — the new key will go through the same broken path.
Never print the full key, even while debugging. A key in a log file is a key in every place that log is shipped to; see the exchange API key security checklist.
What usually comes next
Clearing -2014 often reveals the next layer. The key is now well-formed, so
Binance evaluates it — and you may meet -2015 if the key, IP or permission is
refused, or -1022 if the secret does not match
the key. That sequence is normal: each error is the next check in line, not a
sign that the fix made things worse.
For error handling, -2014 is permanent. It will fail identically until the
configuration changes, so it should stop the process and alert rather than
retry — see error handling patterns for trading APIs.
Where the key lives, and how it gets into the process, is a design question
covered in secrets management for trading bots.
FAQ
What does Binance error -2014 mean?
BAD_API_KEY_FMT — “API-key format invalid.” The value sent in the
X-MBX-APIKEY header is not a well-formed key. Binance’s error list gives no
further causes; in practice it is usually whitespace, a newline or quotes
picked up when the key was loaded, a truncated key, or the wrong value in the
header.
What is the difference between Binance -2014 and -2015?
-2014 is about the format of the key string: the value in the header is not
shaped like a key. -2015 is “Invalid API-key, IP, or permissions for action.”
— the key was well-formed but refused, because it is unknown, the calling IP is
not whitelisted, or the key lacks the permission for that endpoint.
Can a wrong API secret cause -2014?
The secret is not sent in the header; it is used to compute the signature. A
wrong secret would show up as a signature failure, -1022, rather than as a key
format error. If you see -2014, look at what is in the X-MBX-APIKEY header,
including whether the secret was put there by mistake.
Does regenerating the API key fix -2014?
Only if the stored key itself was damaged. If the problem is in how your code loads the key — a newline, quotes, the wrong variable — the new key will be damaged the same way. Test the key in a minimal request first to find out which case you are in.