Les codes d'erreur de l'API Binance utilisent un codage par entiers négatifs, allant de -1000 à -2099. Ils sont divisés en quatre catégories principales : Erreurs générales (-1000 ~ -1199), Erreurs de requête (-1100 ~ -1199), Limitation de fréquence/Contrôle des risques (-1003/-1013) et Erreurs d'ordre (-2010 ~ -2099). Cet article compile plus de 80 codes d'erreur réellement rencontrés en environnement de production, accompagnés de leurs solutions et d'un code middleware de gestion d'erreurs en Python. Pour les lecteurs n'ayant pas encore activé l'API, veuillez d'abord effectuer la vérification KYC sur le Site officiel de Binance. Les nouveaux utilisateurs peuvent s' inscrire gratuitement.
I. Structure de la réponse d'erreur
Toutes les réponses d'erreur de l'API Binance ont un format unifié :
{
"code": -1021,
"msg": "Timestamp for this request is outside of the recvWindow."
}
Le code d'état HTTP est généralement 400 (erreur métier) ou 403/429/418 (erreur de passerelle).
II. Erreurs générales (-1000 à -1099)
| Code | Message | Signification | Solution |
|---|---|---|---|
| -1000 | UNKNOWN | Erreur inconnue | Réessayer ; si elle persiste, contacter le support |
| -1001 | DISCONNECTED | Déconnexion interne du serveur | Attendre 5s et réessayer |
| -1002 | UNAUTHORIZED | Non authentifié | Vérifier l'en-tête X-MBX-APIKEY |
| -1003 | TOO_MANY_REQUESTS | Limite de fréquence dépassée | Attendre le nombre de secondes indiqué par Retry-After |
| -1006 | UNEXPECTED_RESP | Réponse anormale | Réessayer |
| -1007 | TIMEOUT | Délai d'attente dépassé | Augmenter recvWindow |
| -1014 | UNKNOWN_ORDER_COMPOSITION | Composition d'ordre non prise en charge | Vérifier le type d'ordre |
| -1015 | TOO_MANY_ORDERS | Trop d'ordres | Annuler certains ordres non exécutés |
| -1016 | SERVICE_SHUTTING_DOWN | Service en cours d'arrêt | Attendre le rétablissement |
| -1020 | UNSUPPORTED_OPERATION | Opération non prise en charge | Consulter la documentation |
| -1021 | INVALID_TIMESTAMP | Écart d'horodatage | Synchroniser via NTP ou augmenter recvWindow |
| -1022 | INVALID_SIGNATURE | Signature invalide | Vérifier l'algorithme de signature |
Détails sur les erreurs importantes
-1003 TOO_MANY_REQUESTS :
{"code": -1003, "msg": "Too many requests; current limit is 6000 request weight per 1 MINUTE. Please use WebSocket Streams for live updates to avoid polling the API."}
Traitement :
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 60))
time.sleep(retry_after)
# Réessayer ensuite
-1021 INVALID_TIMESTAMP :
{"code": -1021, "msg": "Timestamp for this request is outside of the recvWindow."}
Traitement :
# Option 1 : Synchroniser le décalage temporel du serveur
server_time = requests.get("https://api.binance.com/api/v3/time").json()["serverTime"]
local_time = int(time.time() * 1000)
offset = server_time - local_time # Sauvegarder et ajouter à chaque signature
# Option 2 : Augmenter recvWindow (maximum 60000)
params["recvWindow"] = 10000
-1022 INVALID_SIGNATURE :
{"code": -1022, "msg": "Signature for this request is not valid."}
Causes communes :
- L'ordre des paramètres dans la chaîne de signature diffère de celui de la requête.
- Des guillemets ont été ajoutés aux paramètres numériques.
- La Secret Key est tronquée ou contient des espaces.
- La méthode d'encodage URL est différente.
III. Erreurs de paramètres (-1100 à -1199)
| Code | Message | Signification | Traitement |
|---|---|---|---|
| -1100 | ILLEGAL_CHARS | Caractères illégaux | Nettoyer l'entrée |
| -1101 | TOO_MANY_PARAMETERS | Trop de paramètres | Simplifier les paramètres |
| -1102 | MANDATORY_PARAM_EMPTY_OR_MALFORMED | Paramètre obligatoire vide ou mal formé | Vérifier la documentation API |
| -1103 | UNKNOWN_PARAM | Paramètre inconnu | Supprimer les champs superflus |
| -1104 | UNREAD_PARAMETERS | Paramètres non lus | Supprimer les paramètres redondants |
| -1105 | PARAM_EMPTY | Paramètre vide | Saisir une valeur valide |
| -1106 | PARAM_NOT_REQUIRED | Paramètre non requis | Le supprimer |
| -1111 | BAD_PRECISION | Erreur de précision | Doit respecter LOT_SIZE / PRICE_FILTER |
| -1112 | NO_DEPTH | Carnet d'ordres vide | Attendre le rétablissement du marché |
| -1114 | TIF_NOT_REQUIRED | TIF non applicable | Ne pas envoyer timeInForce pour les ordres au marché |
| -1115 | INVALID_TIF | TIF invalide | Utiliser GTC / IOC / FOK |
| -1116 | INVALID_ORDER_TYPE | Type d'ordre invalide | Vérifier les types pris en charge |
| -1117 | INVALID_SIDE | side invalide | BUY ou SELL |
| -1118 | EMPTY_NEW_CL_ORD_ID | ID d'ordre client vide | Fournir newClientOrderId ou omettre |
| -1119 | EMPTY_ORG_CL_ORD_ID | ID d'ordre d'origine vide | Fournir orderId lors de l'annulation/requête |
| -1120 | BAD_INTERVAL | Intervalle K-line invalide | 1m/5m/15m/1h/4h/1d, etc. |
| -1121 | BAD_SYMBOL | Paire de trading invalide | Appeler exchangeInfo pour vérifier |
| -1125 | INVALID_LISTEN_KEY | listenKey invalide | Rappeler userDataStream |
| -1127 | MORE_THAN_XX_HOURS | Plage de requête trop large | Utiliser plusieurs requêtes |
| -1128 | OPTIONAL_PARAMS_BAD_COMBO | Mauvaise combinaison de paramètres optionnels | Vérifier l'exclusion mutuelle |
| -1130 | INVALID_PARAMETER | Valeur de paramètre illégale | Corriger la plage de valeurs |
| -1131 | INVALID_JSON | Format JSON incorrect | Valider le JSON |
Détails importants
-1111 BAD_PRECISION (Erreur très fréquente) :
Filter failure: LOT_SIZE
Cause : La quantité ou le prix ne respecte pas le stepSize ou le tickSize de la paire de trading.
# Bonne pratique : arrondir après avoir consulté les règles de trading
import math
def get_filters(symbol: str) -> dict:
r = requests.get("https://api.binance.com/api/v3/exchangeInfo",
params={"symbol": symbol}).json()
return {f["filterType"]: f for f in r["symbols"][0]["filters"]}
def round_step(value: float, step: float) -> float:
return math.floor(value / step) * step
filters = get_filters("BTCUSDT")
step_size = float(filters["LOT_SIZE"]["stepSize"]) # 0.00001
tick_size = float(filters["PRICE_FILTER"]["tickSize"]) # 0.01
min_notional = float(filters["NOTIONAL"]["minNotional"]) # 5.0
# Normalisation avant de passer l'ordre
quantity = round_step(0.0015789, step_size) # → 0.00157
price = round_step(60123.4567, tick_size) # → 60123.45
IV. Échec de filtre (-1013)
L'erreur -1013 INVALID_MESSAGE s'accompagne de différents filtres indiquant la cause précise :
| Type de filtre | Signification | Traitement |
|---|---|---|
| PRICE_FILTER | Prix non conforme au tickSize | Arrondir selon tickSize |
| LOT_SIZE | Quantité non conforme au stepSize | Arrondir selon stepSize |
| MIN_NOTIONAL | Valeur totale trop basse (<5 USDT) | Augmenter la quantité |
| NOTIONAL | Valeur notionnelle non conforme | Identique à MIN_NOTIONAL |
| PERCENT_PRICE | Écart de prix trop important | Se rapprocher du prix du marché |
| MARKET_LOT_SIZE | Quantité d'ordre au marché non conforme | Respecter les règles des ordres Market |
| MAX_NUM_ORDERS | Trop d'ordres ouverts sur la paire | Annuler des ordres avant d'en passer d'autres |
| MAX_NUM_ALGO_ORDERS | Trop d'ordres algorithmiques | Annuler certains Take Profit / Stop Loss |
V. Erreurs d'ordre (-2010 à -2099)
| Code | Message | Signification | Traitement |
|---|---|---|---|
| -2010 | NEW_ORDER_REJECTED | Ordre rejeté | Voir le message msg spécifique |
| -2011 | CANCEL_REJECTED | Annulation rejetée | L'ordre est peut-être déjà exécuté |
| -2013 | NO_SUCH_ORDER | L'ordre n'existe pas | Vérifier l'orderId |
| -2014 | BAD_API_KEY_FMT | Format de clé incorrect | Vérifier les 64 caractères |
| -2015 | REJECTED_MBX_KEY | Clé / IP / Permissions incorrectes | Vérifier la liste blanche et les droits |
| -2016 | NO_TRADING_WINDOW | Pas de fenêtre de trading | Paire de trading suspendue |
| -2018 | BALANCE_NOT_SUFFICIENT | Solde insuffisant | Déposer des fonds ou réduire la quantité |
| -2019 | MARGIN_NOT_SUFFICIENT | Marge insuffisante | Réduire le levier ou ajouter de la marge |
| -2020 | UNABLE_TO_FILL | Impossible d'exécuter | Ajuster le prix de l'ordre limite |
| -2021 | ORDER_WOULD_IMMEDIATELY_TRIGGER | L'ordre se déclencherait immédiatement | Ajuster le prix du Stop Loss/Take Profit |
| -2022 | REDUCE_ONLY_REJECT | Reduce-only rejeté | Vérifier la direction de la position |
| -2023 | USER_IN_LIQUIDATION | Utilisateur en liquidation | Attendre la fin de la liquidation |
| -2024 | POSITION_NOT_SUFFICIENT | Position insuffisante | Impossible de fermer autant |
| -2025 | MAX_OPEN_ORDER_EXCEEDED | Nombre max d'ordres ouverts dépassé | Annuler d'anciens ordres |
| -2026 | REDUCE_ONLY_ORDER_TYPE_NOT_SUPPORTED | Type d'ordre non compatible reduce-only | Passer en Market ou Limit |
| -2027 | MAX_LEVERAGE_RATIO | Levier trop élevé | Réduire le levier |
| -2028 | MIN_LEVERAGE_RATIO | Levier trop bas | L'augmenter |
Détails importants
-2010 NEW_ORDER_REJECTED (Le plus courant) :
Le champ msg donnera la raison précise :
"Account has insufficient balance for requested action"→ Solde insuffisant."Order would immediately match and take"→ L'ordre limite s'exécuterait immédiatement (en mode LIMIT_MAKER)."Filter failure: LOT_SIZE"→ La quantité ne respecte pas le pas (stepSize)."Filter failure: PERCENT_PRICE"→ L'écart de prix est trop important.
def place_order_safely(symbol, side, qty, price):
try:
return client.create_order(
symbol=symbol, side=side, type="LIMIT",
timeInForce="GTC", quantity=qty, price=price
)
except BinanceAPIException as e:
if e.code == -2010:
if "insufficient balance" in e.message:
return {"error": "Solde insuffisant"}
if "Filter failure: LOT_SIZE" in e.message:
return {"error": "Erreur de précision, arrondir selon stepSize"}
raise
-2015 REJECTED_MBX_KEY :
Trois sous-causes possibles (à déduire du message d'erreur) :
- Format de clé API incorrect : Vérifier la longueur de 64 caractères.
- IP absente de la liste blanche : Se connecter à Binance pour mettre à jour.
- Permissions non activées : Par exemple, appel de
/fapi/sans avoir coché « Activer les Futures ».
VI. Erreurs liées au contrôle des risques
| Code | Message | Signification | Traitement |
|---|---|---|---|
| -4001 | PRICE_LESS_THAN_ZERO | Prix négatif | Vérifier les paramètres |
| -4002 | PRICE_GREATER_THAN_MAX_PRICE | Prix supérieur au max | Baisser le prix |
| -4003 | QTY_LESS_THAN_ZERO | Quantité négative | Passer en positif |
| -4004 | QTY_LESS_THAN_MIN_QTY | Quantité inférieure au min | Voir LOT_SIZE |
| -4005 | QTY_GREATER_THAN_MAX_QTY | Quantité supérieure au max | Passer l'ordre en plusieurs fois |
| -4006 | STOP_PRICE_LESS_THAN_ZERO | Prix de stop négatif | Corriger |
| -4164 | MIN_NOTIONAL | Valeur notionnelle inférieure à 5 USDT | Augmenter la quantité |
| -5021 | FOK_ORDER_REJECT | Ordre FOK rejeté | Liquidité insuffisante, passer en GTC |
| -5022 | GTX_ORDER_REJECT | Ordre GTX (Post Only) rejeté | Le prix du marché a changé, le prix n'est plus en attente |
VII. Middleware unifié de gestion d'erreurs (Python)
import time
import requests
from typing import Optional
class BinanceAPIError(Exception):
def __init__(self, code: int, msg: str, raw: dict):
self.code = code
self.msg = msg
self.raw = raw
super().__init__(f"Binance {code}: {msg}")
def handle_response(response: requests.Response) -> dict:
data = response.json()
if "code" in data and data["code"] < 0:
raise BinanceAPIError(data["code"], data.get("msg", ""), data)
return data
def request_with_recovery(method, url, **kwargs) -> Optional[dict]:
for attempt in range(5):
try:
r = requests.request(method, url, **kwargs)
if r.status_code == 429:
retry_after = int(r.headers.get("Retry-After", 60))
print(f"Limite atteinte, attente de {retry_after}s")
time.sleep(retry_after)
continue
if r.status_code == 418:
raise SystemExit("IP bannie, fin du programme")
data = handle_response(r)
return data
except BinanceAPIError as e:
if e.code == -1021:
print("Écart d'horodatage, nouvelle synchronisation")
# Réessayer après synchronisation
continue
if e.code in (-1001, -1006, -1007):
wait = 2 ** attempt
print(f"Erreur temporaire {e.code}, nouvel essai dans {wait}s")
time.sleep(wait)
continue
# Les erreurs métier non reproductibles sont levées directement
raise
return None
VIII. Questions fréquemment posées (FAQ)
Q1 : Que faire si l'erreur -1021 apparaît de manière répétée ?
R : Problème d'horloge système. Sous Linux, activez chronyd :
sudo systemctl enable chronyd
sudo chronyc sources -v # Vérifier les sources de synchronisation
Sous Windows, allez dans Panneau de configuration → Date et heure → Temps Internet → Synchroniser avec time.windows.com.
Q2 : Quelle est la cause de l'erreur -1015 TOO_MANY_ORDERS ?
R : Le nombre d'ordres en attente non exécutés sur une seule paire dépasse 200 (Spot) ou la limite supérieure fixée par le filtre MAX_NUM_ORDERS. Il suffit d'annuler certains ordres dont le prix est éloigné du cours actuel.
Q3 : Pourquoi l'erreur -2015 persiste-t-elle après avoir vérifié les permissions et l'IP ?
R : Vérifiez si vous utilisez une clé Spot sur un domaine Futures (fapi.binance.com) ou inversement. Les droits requis pour le Spot et les Futures sont différents. Même si une clé est valide, elle ne fonctionnera pas sur les interfaces Futures si l'option « Activer les Futures » n'est pas cochée.
Q4 : Comment enregistrer tous les codes d'erreur dans les logs ?
R : Encapsulez une couche middleware pour compter les erreurs par code :
from collections import Counter
error_counter = Counter()
def log_error(code: int):
error_counter[code] += 1
if error_counter[code] > 100:
alert(f"L'erreur {code} s'est produite {error_counter[code]} fois, problème système potentiel")
Q5 : Quelle est la différence entre -1013 et -2010 ?
R : -1013 est une erreur de filtre (paramètres non conformes aux règles de trading), tandis que -2010 est un rejet d'ordre (rejet par la couche métier, la raison est précisée dans msg). L'erreur -1013 peut généralement être évitée par un calcul préalable côté client, alors que -2010 dépend davantage de l'état du marché en temps réel (solde, glissement, contrôle des risques).
Après avoir consulté la liste des codes d'erreur, revenez à la Navigation par catégorie pour découvrir d'autres sujets techniques dans la catégorie « Intégration API ».