Binance API error -1102: mandatory parameter empty or malformed
Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs.
Binance error -1102 is MANDATORY_PARAM_EMPTY_OR_MALFORMED. It comes with
one of three messages, and two of them name the parameter for you:
- “A mandatory parameter was not sent, was empty/null, or malformed.”
- “Mandatory parameter ‘%s’ was not sent, was empty/null, or malformed.”
- “Param ‘%s’ or ‘%s’ must be sent, but both were empty/null!”
The %s is filled in with a parameter name. That name is most of the
diagnosis. USDⓈ-M futures documents the same three messages; Spot adds further
variants for its FIX interface.
The part people get stuck on is the phrase “was not sent”, because they did send it. This page is about the gap between the parameter you meant to send and the one that arrived.
What this error actually means
One code, three different failures:
| Wording | What arrived at Binance |
|---|---|
| “was not sent” | No parameter by that name at all |
| “was empty/null” | The name arrived with no usable value |
| “malformed” | A value arrived that could not be read as the expected type |
Binance does not tell you which of the three applied. You find out by looking at the request as it went on the wire.
The request was rejected before anything happened, so there is nothing to reconcile. It is also a permanent error in the sense used in error handling patterns for trading APIs: the same request fails the same way every time, so fix it rather than retry it.
The usual cause: your value serialised into nothing
In practice, the most common -1102 is a value that exists in your code and
disappears on the way to the wire.
- A null that became an empty string, producing
price=in the query. - A null the HTTP library dropped entirely, so the parameter is absent.
- A null that became a literal word —
price=Noneorprice=null— which is a value, but not a number. - A misspelt key. Parameter names are matched as documented; a key with the wrong case or a typo means the correctly named parameter “was not sent”.
A related version is the conditionally required parameter. Which parameters an order needs depends on its type, and the endpoint’s documentation lists the requirements per type. Code that switches order type while reusing the same parameter set will send a request that is complete for one type and incomplete for the other.
Other causes, in order of likelihood
1. Numbers in a format Binance cannot read. A float formatted by default can
come out in scientific notation — 1e-05 instead of 0.00001 — and some locales
write a decimal comma. Format numeric parameters explicitly as plain decimal
strings. This one is especially easy to miss because it only appears for very
small or very large values.
2. Parameters in the wrong place. Binance signs the query string
concatenated with the body, but an endpoint still has to read the parameters
from where you put them. In practice, a body attached to a request type that
does not normally carry one may simply not be read — and the first parameter
Binance looks for, often timestamp or signature, “was not sent”.
3. The “or” message. “Param ‘%s’ or ‘%s’ must be sent, but both were empty/null!” is for endpoints that accept either of two alternative parameters. In practice the common pair is two ways of identifying the same order — an exchange order ID and a client order ID. Send exactly one of them, populated.
4. A futures mode change. On USDⓈ-M futures the account’s position mode
changes which parameters an order needs. Binance documents that positionSide
defaults to BOTH in One-way Mode and “must be sent in Hedge Mode”, and that
reduceOnly “cannot be sent in Hedge Mode”. The mode is an account setting that
applies to every symbol, and after the CM migration changing it flips USDⓈ-M and
COIN-M together. So someone switching mode from another tool can change what
your bot is required to send without touching its code. A position side that
does not match the mode is documented as -4061; we did not find which code an
omitted positionSide returns, so if an order that used to work starts failing
around positionSide, check the mode.
5. An outdated client. A library or wrapper written against an older version of an endpoint may not send something the current version requires; see API versioning and breaking changes.
How to confirm which one you have
Log the request exactly as it went out — the full URL and the raw body — not the dictionary you built it from. Then find the parameter the message named:
| What you see on the wire | Cause |
|---|---|
| Parameter absent | Not sent: misspelt key, null dropped by the library, or a conditional parameter missing for this order type |
name= with nothing after it | Empty: a null or empty string serialised |
name=None, name=null | A null serialised as a word |
name=1e-05 or a decimal comma | Malformed number |
| Present and correct in the body | Check the endpoint reads it from the body |
| Two alternatives, both empty | The “or” message: populate one |
If the message did not name a parameter, work through the endpoint’s required list against the wire request in order.
One trap when fixing it: add the missing parameter before signing, never
after. Appending it to an already-signed request changes the payload the
signature covers, and the next error you see will be
-1022 instead. Build the full parameter set,
then sign, then send — the same string throughout.
Where it sits among Binance’s request errors
-1102 is about whether a parameter arrived in usable form. It is separate from
the errors about the parameter’s value being unacceptable once read:
-1121 when the symbol is not recognised,
-1013 when an order fails a symbol filter on
Spot. And it is separate from the key and permission family —
-2015 and its neighbours — which is about who
is asking rather than what they sent.
FAQ
What does Binance error -1102 mean?
MANDATORY_PARAM_EMPTY_OR_MALFORMED — a required parameter was missing, empty
or null, or not in a readable format. Two of its three messages name the
parameter, which tells you where to look. Log the request as sent on the wire
and check that parameter’s name, presence and format.
Why does Binance say a parameter was not sent when I sent it?
Usually because it did not survive serialisation. A null value can be dropped by
the HTTP library, turned into an empty string, or written as the word None or
null; a misspelt key means the correctly named parameter is absent. Compare
the raw request on the wire with what your code intended.
What does “Param ‘%s’ or ‘%s’ must be sent, but both were empty/null!” mean?
The endpoint accepts either of two alternative parameters, and neither arrived with a value. In practice this is usually two ways of identifying the same order. Send exactly one of the two, with a value, and check that your library did not drop it because it was built from a null.
Does Binance futures return the same -1102 messages?
USDⓈ-M futures documents -1102 with the first three Spot messages. Futures
adds its own ways to trigger it: whether an order needs positionSide depends
on the account’s position mode, which is set for every symbol at once and can be
changed outside your code.