During the development and teaching of bot programming for Binance, I had and helped to solve several different errors related to the APIs. The idea of this article is to serve as a reference for such errors and help other devs who are experiencing any of them.
For common HTTP errors (400, 403, 500, etc), see this other generic post for HTTP status.
For a complete list of Spot bugs, consult the official documentation. For a complete list of Futures bugs, see the official documentation.
Use your browser’s search function (Ctrl+F) and look for a word in your error to find it easier on this page. If you’re in my course group on Telegram, use the group search to find answers there too.
Errors involving Keys
Before any mistake, if you don’t know how to create your test and production keys correctly, learn from the video below for Binance Spot. Further the video for Binance Futures. Some students reported not being able to create the keys on their machine following the instructions below, perhaps due to some Binance block or restriction, and that they resolved using another computer and/or another IP.
Here’s the video teaching how to create the keys for Binance Futures.
Errors with Testnet vs Production URLs
Many of the errors are caused by invalid URLs, so I open this article by bringing test and production URLs for Spot and Futures markets. For Spot, the URLs are listed here, and for Futures, they are listed here. Note that when you are pointing your bot to Testnet, you must use test keys, otherwise production keys.
Invalid API-Key, IP, or permissions for this action.
This error is when you try to access a private API, which requires authentication, and you have invalid keys (you can recreate with the instructions from the previous videos) or when you are already operating with the production URLs and have not authorized the IP of the machine where your robot in creating the API key. Or even if you don’t have spot permissions on the keys.
In the case of Futures, you need to answer the Binance questionnaire before being able to add the futures permission to your API key. You answer it the first time you access the futures trade screen (you may have to change the site language to access this screen). And in the case of the withdrawal API (withdraw), it has specific permission to be added in the key as well.
balanceData error
This error happens when we try to connect to the wallet API to get the user’s coin balance. It happens when your keys are invalid (recreate) or your machine’s time is wrong, which is common in Windows. Many of my students use this tool to fix time problems: Time Sync Tool while on Linux the commands below have proven to be useful:
sudo apt-get install ntp ntpdatesudo ntpdate pool.ntp.orgSignature for this request is not valid
This error usually happens when your API secret is wrong, but it can also be a failure in your request signing function (HMAC-SHA).
When I refer to the wrong API secret, it can either be incorrectly informed, missing characters, changed characters, or even not being the secret for the API Key informed in the request. I’ve also seen it happen because the student used Testnet Spot keys in Testnet Futuros, which doesn’t work.
Invalid API Secret
Indicates that your API Secret is invalid or missing.
Api-key format invalid.
Indicates that your API Key is invalid or missing.
Service unavailable from a restricted location according to ‘b. Eligibility’ in https://www.binance.com/en/terms. Please contact customer service if you believe you received this message in error.
This message indicates that you are using the Binance API from a region they are not allowed to operate in and therefore have blocked your key. Binance.com cannot operate in the US, for example, there they have BinanceUS, for Americans only. Other countries it cannot operate include China, the Ontario region of Canada, and others. Unfortunately, I don’t have the complete list, but I remember that from Brazil, India, and Germany it was fine to use the APIs.
Unexpected Server Response: 451
Same as the previous error. 451 is the HTTP code for Unavailable for Legal Reasons.
Errors involving Orders
Filter Failure
Filter errors indicate that your order is not respecting any exchange rules. Next to the filter failure will say which rule. The complete rules for all symbols can be found in the exchangeInfo API, you can access it, save the JSON, and search for your symbol in it.
Invalid quantity, Min. Lot Size, MIN_LOT_SIZE, LOT_SIZE ou Step Size
All errors containing these words are related to the order quantity parameter. They indicate that the amount submitted as quantity does not meet the lot size rules for that currency pair. It is often the excessive number of decimal places being used or a size smaller than the minimum batch. The complete lot size rules for all symbols can be found in the exchangeInfo API, you can access it, save the JSON, and search for your symbol in it. The video below explains everything.
MIN_NOTIONAL, PRICE_FILTER, Min. Notional and Tick Size
All errors containing these words are related to the order price parameter. They indicate that the amount submitted as a price does not meet the nominal price rules for that currency pair. For example, the minimum value of each order cannot be less than 10 USD in all pairs of USD, USDT, etc. The complete price rules for all symbols can be found in the exchangeInfo API, you can access it, save the JSON, and search for your symbol in it. The video below explains it all.
Order with EXPIRED status
This is not a programming error but is a common occurrence on Testnet with many currency pairs. As Testnet does not have liquidity, since it is a market only for devs operating with their bots, many pairs, when receive an order in the book, cannot execute it because no one is willing to buy their sell order or vice versa. I only recommend testing using the BTCUSDT pair, which is the most liquid and least likely to make this error.
Order would immediately trigger or Stop price would trigger immediately.
This error indicates that the price trigger you set doesn’t make sense, as it would trigger immediately. If you want to trigger an order immediately, use market orders. If you want to use stops and limits, you must define future price triggers which do not trigger immediately.
Taken from official Binance documentation:
-> SELL: Limit Price > Last Price > Stop Price
-> BUY: Limit Price < Last Price < Stop Price
Account has insufficient balance for requested action.
This error indicates that you don’t have enough balance for the action. If you’re trying to sell BTCUSDT, make sure you have enough BTC for the sale you want. If you are buying BTCUSDT, make sure you have enough USDT for the purchase.
Usually, when students have this error, it’s because they are sending the wrong amount of information or don’t have a balance.
Precision is over the maximum defined for this asset.
This error indicates that you are using too many decimal places in your operation. The complete precision rules for all symbols can be found in the exchangeInfo API, you can access it, save the JSON, and search for your symbol in it.
Errors involving Streams
Web Socket Error: Closed, Reconnecting, ETIMEDOUT, EAI_AGAIN, ERR_SOCKET_CONNECTION_TIMEOUT, hang up, etc
All errors containing these words are linked to connectivity issues with Binance streams (websockets). Next to the error, there is information about which stream it tried to connect to, so it is worth checking if it is correctly named according to the streams documentation. If everything is programmed correctly, it is possibly a problem with the user’s Internet or some temporary unavailability of Testnet (very rare, only during maintenance).
One last point in this item concerns the version of Node.js. At the time I write this post, the recommended Node version is 18 (LTS), and it is very common for version 20 to have problems with streams/websockets, which should be corrected when it becomes stable (LTS).
Failed to construct WebSocket.
This error is when you are making a mistake in building the stream URL.
userDataStream:subscribed:undefined
Indicates that it was unable to connect to the user’s data stream, possibly due to credential or URL issues.
The URL scheme must be ws or wss. The URL scheme must be ws or wss.
This means that your websocket URL is wrong, starting with HTTP.
Event isTrusted
This means that your front end lost connection with the websocket it was connected to, possibly because the connection dropped on the other side.
Errors involving environment and design
The property options.family must be one of: 0, 4, 6. Received false.
This DNS error is caused by Node.js versions higher than 16, which is recommended in my courses. I can’t say yet the cause, but the solution is to use version 16.
Cannot find module… e MODULE_NOT_FOUND
It doesn’t matter the module, if you get this error, it’s because you wrote its name wrong, the path to it wrong (if it’s a module itself), or you forgot to install it in the project (if it’s an NPM module).
Timestamp for this request was 1000ms ahead of the server’s time.
This error indicates that your machine’s time is ahead, a common problem in Windows, rare in Linux, and non-existent in Mac so far. Many of my Windows students have used this tool to fix time problems: Time Sync Tool
On Linux, the solution I have is using these commands:
sudo apt-get install ntp ntpdatesudo ntpdate pool.ntp.orgTimestamp for this request is outside of the recvWindow.
Another error is linked to the time of your machine or the slowness of your Internet. To resolve the time issue, use the same tip as before and optionally increase the delay tolerance, which by default is 5000ms and can have a maximum of 60000ms. The recvWindow is a parameter that you must pass along with your request data, as in the example below, where I set it to the maximum.
async function newOrder(symbol, quantity, side) {
const data = { symbol, quantity, side };
data.type = “MARKET”;
data.timestamp = Date.now();
data.recvWindow = 60000;
Network Error e ERR_CONNECTION_REFUSED
The backend/API you are trying to access is down, or you entered the wrong address.
…is not defined
It doesn’t matter what comes before, it means that you tried to access a property of an undefined object, which is empty, probably a problem in your logic.
EADDRINUSE ou address already in use
Your machine is already running a bot on this same port. Terminate its execution or run it on another port.
DeprecationWarning
This is not an error, it’s a warning, but it confuses, so it’s worth explaining that this warning indicates that some package or function has fallen into disuse, but still works. It is recommended to move to a newer package or function.
found x vulnerabilities
This is not an error, it’s a warning, but it confuses so, it’s worth explaining that this warning indicates that some package had a vulnerability/security flaw found. It is recommended to switch to a newer or more secure package.
Query.run
This is a Sequelize misuse error and happens when the model used in the query is different from the database table.
Access denied for user … using password: YES
You have an incorrect database username or password.
If your mistake is not here, leave it in the comments below. Another excellent source for understanding Binance documentation is the video below.
*The content of this article is the author’s responsibility and does not necessarily reflect the opinion of iMasters.
Leave a comment