Rate limits and recovery
Track shared request budgets and resolve uncertain orders before retrying.
Track the response headers
Read the configured one-minute limits from exchangeInfo. The current default is 2400 request weight per IP, another 2400 per verified Trading Account, and 1200 successful order placements per Trading Account.
All credentials on a Trading Account share its account budgets. Signed requests and Listen Key operations consume account request weight. Reads and cancellations do not consume the order-placement allowance.
An admitted request consumes weight even if authentication or validation later fails. Outstanding order reservations can exhaust capacity while the completed-placement header remains below the limit.
| Header | Meaning |
|---|---|
| X-MBX-USED-WEIGHT-1M | Admitted request weight for the source IP |
| X-DP-ACCOUNT-USED-WEIGHT-1M | Admitted request weight for the verified Trading Account |
| X-MBX-ORDER-COUNT-1M | Completed successful placements for the verified Trading Account |
Budget by endpoint
HTTP 429 with code -1003 means a request or order budget is exhausted. Back off and reduce concurrency. Sending the same request repeatedly does not make the budget recover faster.
| Weight | Operations |
|---|---|
| 30 | Income history |
| 5 | Depth, candles, order history, fills, funding history, account, balance and positions |
| 1 | Other supported REST operations |
Handle errors by code
Trading API errors use a JSON object with code and msg. Check the HTTP status and numeric code, then use the message for the specific rejection detail.
| Code | What to check |
|---|---|
| -2014 / -2015 | API-key format, current authority, permission and source policy |
| -1022 | Secret, exact signed bytes and final signature parameter |
| -1021 | Clock offset and receive window |
| -1102 | Missing, empty or malformed required parameters |
| -1013 / -1111 | Symbol filters and decimal precision |
| -2019 / -2027 | Available margin and the leverage bracket's notional cap |
| -1003 | Request or order budget; back off |
| -1008 | Temporary readiness, market-data availability or overload |
| -1000 | Internal failure; resolve a mutation's outcome before retrying |
Resolve an uncertain command
A lost response, timeout or internal failure does not prove an order failed. Disconnecting the HTTP request does not cancel a command already accepted for execution.
Use a client order ID to correlate the command. Query the order and open orders, then inspect balances and positions when needed. Do not submit another order while the original outcome remains unresolved.
newClientOrderId is unique among open orders for the symbol. It is not a permanent idempotency token: reuse after an order becomes historical can create another order. Stored history may lag, so an immediate empty history result is not proof of failure.