Binance API Error Code List: Complete Trader's Guide

If you've built a trading bot or written any automation against Binance, you've hit error codes. That -1121 that killed your order at 3am. The -2010 that fires right when volatility spikes and your bot tries to place 40 orders in two seconds. These aren't random noise — every code is specific, and once you understand what each one means, debugging goes from guesswork to a five-minute fix.

This guide covers the full Binance REST API error code list, what triggers each one, and how to handle them correctly in production Python code. The same principles apply whether you're on Binance Spot, Futures, or Margin — and many of these patterns translate directly to Bybit, OKX, and other exchange APIs that follow similar conventions.

Understanding Binance API Error Structure

Every error response from the Binance API follows the same JSON shape: a numeric code and a human-readable message. The code is what matters for programmatic handling — the message is helpful for logging but you should never parse it for logic.

import requests
import hmac
import hashlib
import time
from urllib.parse import urlencode

API_KEY = 'your_api_key'
API_SECRET = 'your_api_secret'
BASE_URL = 'https://api.binance.com'

def get_signed_params(params: dict) -> dict:
    params['timestamp'] = int(time.time() * 1000)
    query_string = urlencode(params)
    signature = hmac.new(
        API_SECRET.encode('utf-8'),
        query_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    params['signature'] = signature
    return params

def place_order(symbol: str, side: str, quantity: float):
    endpoint = '/api/v3/order'
    params = get_signed_params({
        'symbol': symbol,
        'side': side,
        'type': 'MARKET',
        'quantity': quantity
    })
    headers = {'X-MBX-APIKEY': API_KEY}
    response = requests.post(BASE_URL + endpoint, params=params, headers=headers)
    data = response.json()
    
    if 'code' in data:
        print(f'Error {data["code"]}: {data["msg"]}')
        return None
    return data

The critical thing to notice: Binance returns HTTP 200 even for some errors. Always check for the 'code' key in the response body, not just the HTTP status code. Relying only on status codes will cause silent failures in your bot.

System and Network Error Codes (-1000 to -1099)

These codes indicate problems on Binance's infrastructure side, or malformed requests before they reach order processing logic. Most -1xxx errors are your code's fault, not Binance's.

Time sync is the most common silent killer. The -1021 INVALID_TIMESTAMP error fires when your system clock drifts more than 1000ms from Binance's server time. Run NTP sync on any server running a bot, and call GET /api/v3/time periodically to verify your offset stays within bounds.

Request and Parameter Error Codes (-1100 to -1199)

These are validation errors — your request reached Binance but failed parameter checks before any order logic ran. They're the easiest to fix once you know what each one means.

A practical pattern when hitting -1111 (bad precision): Binance's exchange info endpoint tells you the exact step size for each symbol. Fetch it once at startup and use it to round quantities before placing orders. This eliminates an entire class of errors.

import math

def get_step_size(symbol: str) -> float:
    """Fetch the minimum quantity step size for a symbol."""
    response = requests.get(f'{BASE_URL}/api/v3/exchangeInfo?symbol={symbol}')
    info = response.json()
    for filt in info['symbols'][0]['filters']:
        if filt['filterType'] == 'LOT_SIZE':
            return float(filt['stepSize'])
    return 0.001  # fallback

def round_step(quantity: float, step_size: float) -> float:
    """Round quantity down to the nearest valid step."""
    precision = int(round(-math.log10(step_size)))
    return round(math.floor(quantity / step_size) * step_size, precision)

# Usage
step = get_step_size('BTCUSDT')
qty = round_step(0.00314159, step)
print(f'Rounded quantity: {qty}')  # e.g. 0.003

Order and Trading Error Codes (-2010 to -2015)

This range is where most trading bot failures live. These errors fire during order placement and modification — after parameter validation passes but before the order hits the matching engine successfully.

The -2010 code is intentionally vague — Binance uses it as a bucket for many rejection reasons. The actual reason lives in the 'msg' field. Common messages inside -2010: 'Account has insufficient balance', 'Filter failure: PRICE_FILTER', 'Filter failure: MIN_NOTIONAL'. Build a handler that logs the full message for this specific code.

import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('binance_bot')

RETRYABLE_CODES = {-1000, -1001, -1006, -1007}
RATE_LIMIT_CODES = {-1003, -1015}

def safe_place_order(symbol: str, side: str, quantity: float, max_retries: int = 3):
    endpoint = '/api/v3/order'
    
    for attempt in range(max_retries):
        params = get_signed_params({
            'symbol': symbol,
            'side': side,
            'type': 'MARKET',
            'quantity': quantity
        })
        headers = {'X-MBX-APIKEY': API_KEY}
        
        try:
            response = requests.post(BASE_URL + endpoint, params=params, headers=headers, timeout=5)
            data = response.json()
        except requests.exceptions.Timeout:
            logger.warning(f'Attempt {attempt+1}: Request timed out, retrying...')
            time.sleep(2 ** attempt)
            continue
        
        if 'code' not in data:
            logger.info(f'Order placed: {data["orderId"]}')
            return data
        
        code = data['code']
        msg = data.get('msg', '')
        
        if code in RATE_LIMIT_CODES:
            wait = 60 if code == -1003 else 10
            logger.warning(f'Rate limit hit (code {code}), waiting {wait}s')
            time.sleep(wait)
            continue
        elif code in RETRYABLE_CODES:
            logger.warning(f'Retryable error {code}: {msg}, attempt {attempt+1}')
            time.sleep(2 ** attempt)
            continue
        elif code == -2010:
            logger.error(f'Order rejected — full message: {msg}')
            return None  # Don't retry rejections
        elif code == -1021:
            logger.error('Timestamp error — check system clock sync')
            return None
        else:
            logger.error(f'Unhandled error {code}: {msg}')
            return None
    
    logger.error(f'Max retries reached for {symbol} {side}')
    return None

Rate Limits: The Most Expensive Errors to Ignore

Binance enforces multiple rate limit tiers simultaneously. Ignoring them doesn't just cost you errors — it gets your IP or API key banned. The limits are tracked in response headers on every successful request.

• REQUEST_WEIGHT: Default 1200 weight per minute per IP. Each endpoint costs different weight — order placement costs more than price queries.
• ORDER_COUNT: 10 orders/second, 100,000 orders/24h per account. This is separate from request weight.
• RAW_REQUESTS: 61,000 raw HTTP requests per 5 minutes. Rarely hit but exists.
• If you exceed REQUEST_WEIGHT, Binance returns -1003 and bans the IP for varying durations (seconds to hours depending on severity).
• Headers to watch: X-MBX-USED-WEIGHT-1M (current weight used), X-MBX-ORDER-COUNT-10S, X-MBX-ORDER-COUNT-1D

Bybit and OKX use similar rate limit structures, and tools like VoiceOfChain that aggregate real-time signals across multiple exchanges are specifically designed to handle the edge case where you need to act fast on a signal without burning your rate limit budget on price polling. Instead of hammering the API for price updates, you consume a WebSocket or signal stream and reserve your weight budget for actual order operations.

Frequently Asked Questions

Building Resilient API Integrations

The traders who get burned by API errors aren't the ones who hit them — everyone hits them. The ones who get burned are those without systematic error handling. A production bot needs to distinguish between errors that warrant a retry, errors that indicate a logic bug in your code, and errors that require human attention.

Platforms like VoiceOfChain handle this at the infrastructure level for signal delivery — the signal reaches you reliably regardless of what's happening at the exchange API layer. Your job as the bot developer is to handle the execution side: validate your order parameters against live exchange info, respect rate limits proactively rather than reactively, and build an alerting layer that pages you when error rates spike unexpectedly.

The Binance error code system is well-documented and consistent — once you've mapped your error handler to cover the codes in this guide, you've covered the vast majority of what you'll encounter in production. The same disciplined approach works whether you're trading on Binance Spot, Binance Futures, or expanding to Bybit, OKX, or KuCoin — the specifics differ, but the architecture is identical.