When working with the Binance Spot API, encountering error codes is inevitable—especially during integration, testing, or high-frequency trading operations. Understanding these errors thoroughly can significantly reduce debugging time and improve the reliability of your trading systems.
This comprehensive guide walks you through common Binance API error codes grouped by category, explains their meanings, and provides actionable solutions. Whether you're a developer building a bot or managing automated strategies, this resource will help you diagnose issues faster and maintain smooth API interactions.
Understanding Binance API Error Structure
Binance REST and WebSocket APIs return standardized error responses when a request fails. Each error includes two key components:
{
"code": -1121,
"msg": "Invalid symbol."
}code: A numeric identifier representing the general error category.msg: A descriptive message offering more context about the failure.
While some errors originate from the server layer, others stem from invalid parameters or account-specific restrictions. Properly interpreting both elements ensures accurate troubleshooting.
👉 Discover how to build resilient trading bots with real-time data and secure API handling.
10xx Series: Server or Network-Related Errors
These errors typically indicate backend issues, connectivity problems, or rate-limiting policies.
-1000 Unknown Error
A generic server-side error occurred. While rare, it may resolve on retry.
Solution: Implement exponential backoff and retry logic for transient failures.
-1001 Disconnected
Internal server disconnection.
Cause: Temporary network instability or internal service interruption.
Fix: Reconnect and retry the request after a short delay.
-1002 Unauthorized
Authentication failed due to missing or invalid credentials.
Common causes:
- Missing or malformed API key
- Incorrect signature generation
Recommendation: Double-check your authentication headers and ensure proper HMAC-SHA256 signing.
-1003 Too Many Requests
Rate limit exceeded at the IP or user level.
Possible messages:
- Queue overloaded
- Weight limit exceeded (e.g., “X requests per Y seconds”)
- IP temporarily banned
Best practice: Use Websocket streams for real-time updates instead of polling REST endpoints frequently.
👉 Learn how to optimize API usage with low-latency market data feeds.
-1007 Timeout
The backend service did not respond within the allowed timeframe.
Implication: Order status is unknown—verify execution via order query endpoints.
-1008 SERVER_BUSY
Spot trading engine is overloaded.
Action: Wait a few minutes before retrying. Avoid aggressive retry loops.
-1013 Invalid Message
Request rejected before reaching the matching engine.
Root causes:
- Fails input validation filters
- Violates trading rules (see Order Filters section)
Refer to Order Failed by Filter for detailed diagnostics.
-1021 Timestamp Issues
Time synchronization between client and server is out of bounds.
Error types:
- Request timestamp outside
recvWindow - Client clock ahead by more than 1 second
Fix: Sync system time using NTP; adjust recvWindow cautiously (default: 5000ms).
-1022 Invalid Signature
Signature mismatch between client and server computation.
Cause: Incorrect secretKey used in HMAC generation.
Security tip: Store secrets securely and rotate keys periodically.
11xx Series: Request Content Errors
These errors arise from malformed or logically inconsistent API requests.
-1100 Illegal Characters
Invalid characters detected in a parameter.
Example: Sending <script> in a symbol field.
Prevention: Sanitize inputs and validate against allowed character sets.
-1101 Too Many Parameters
Endpoint received more parameters than expected.
Includes cases:
- Exceeding defined parameter count
- Duplicate parameter names
Always refer to official endpoint documentation for required/optional fields.
-1102 Missing Mandatory Parameter
Required field missing, null, or malformed.
Tip: Use structured request builders to avoid omitting critical fields like symbol, side, or timestamp.
-1103 Unrecognized Parameter
An undefined parameter was included in the request.
Debug step: Review spelling and version compatibility—some parameters are introduced in newer API versions.
-1111 Precision Too High
Price or quantity exceeds allowed decimal places.
Each symbol enforces precision via exchange filters (e.g., PRICE_FILTER, LOT_SIZE).
Check: Use /api/v3/exchangeInfo to retrieve symbol-specific constraints.
-1121 Invalid Symbol
The trading pair does not exist or is misspelled.
Example: Requesting BTCUSDTT instead of BTCUSDT.
Validation: Confirm supported symbols via the exchange info endpoint.
Order-Specific Errors (-20xx Series)
These originate from the matching engine and reflect business logic violations.
-2010 NEW_ORDER_REJECTED
Order rejected due to various conditions:
| Message | Meaning |
|---|---|
"Account has insufficient balance" | Not enough funds for purchase |
"Market is closed" | Trading disabled for this symbol |
"Price * QTY is zero or less" | Invalid order value |
"Order would immediately match and take" | LIMIT_MAKER would become taker |
👉 Avoid common order rejections with pre-trade validation tools.
-2013 Order Does Not Exist
Attempted operation on non-existent order.
Causes:
- Incorrect
orderIdorclientOrderId - Order already filled or canceled
Always track order state changes via user data streams.
-2015 Invalid API-Key, IP, or Permissions
Critical access denial.
Breakdown:
- API key doesn’t exist
- Request from disallowed IP
- Missing required permissions (e.g.,
TRADE,USER_DATA)
Ensure correct configuration in your Binance API settings dashboard.
Order Failed by Filter
Orders may fail due to exchange-defined filters. Below are common filter-based rejections:
| Filter | Description |
|---|---|
| PRICE_FILTER | Price outside min/max or violates tick size |
| LOT_SIZE | Quantity below minimum, above maximum, or step size mismatch |
| MIN_NOTIONAL | price × qty < minimum allowed value |
| ICEBERG_PARTS | Iceberg order exceeds max visible parts |
| MAX_NUM_ORDERS | Account-level limit on open orders reached |
Use /api/v3/exchangeInfo to programmatically fetch current filter values per symbol.
Frequently Asked Questions (FAQ)
What does "Invalid Symbol" (-1121) mean?
It means the trading pair you're trying to access either doesn't exist, is misspelled, or isn't supported in your requested context (e.g., spot vs futures). Always verify symbol names using the /exchangeInfo endpoint.
How do I fix timestamp errors (-1021)?
Ensure your system clock is synchronized with an NTP server. You can also increase the recvWindow parameter (up to 60,000ms), but this should be a last resort—not a permanent fix.
Why was my order rejected even with correct syntax?
Even if your request is well-formed, business rules may block execution. Common reasons include insufficient balance, price filters, market closure, or account restrictions. Check the msg field for specific details.
Can I prevent rate limiting (-1003)?
Yes. Optimize by:
- Using Websocket streams instead of frequent polling
- Distributing requests across multiple IPs (if applicable)
- Respecting documented rate limits per endpoint
What’s the difference between -1013 and -2010?
Error -1013 means the request was rejected before reaching the matching engine (validation failure). -2010 means it reached the engine but was rejected based on trading logic (e.g., balance, price).
How do I handle cancel-replace failures (-2021, -2022)?
-2021: Either cancel or new order failed; check response details.-2022: Both operations failed.
Implement fallback logic: query order status and retry if necessary.
Final Tips for Robust API Integration
- Log all errors with timestamps
- Implement idempotency using
newClientOrderId - Monitor rate limits proactively
- Use WebSockets for order updates
- Validate inputs against exchangeInfo before sending
By mastering Binance API error codes, you enhance system stability, reduce downtime, and build more intelligent trading logic. Stay proactive—anticipate errors rather than react to them.