Trade
Perps
Lend
Dashboard
DocsError Handling
Complete guide to handling API errors and HTTP status codes on Bond.
HTTP Status Codes
Client Errors (4XX)
400
Bad Request - malformed or missing required parameters
403
Forbidden - WAF limit violated
408
Request Timeout - backend response timeout
418
IP Auto-banned - repeated 429 violations
429
Too Many Requests - rate limit exceeded
Server Errors (5XX)
500
Internal Server Error
503
Service Unavailable (see detailed handling below)
HTTP 503: Detailed Handling
Variant A: Unknown Execution Status
"Unknown error, please check your request or try again later."
The API sent the request but did not get a response within timeout. Execution status is UNKNOWN and could have succeeded. Do NOT treat this as a failure. Verify via WebSocket or query by orderId before retrying.
Rate limit
May or may not count - check response headers
Variant B: Service Unavailable
"Service Unavailable."
Service temporarily unavailable. 100% failure. Retry with exponential backoff (200ms, 400ms, 800ms). Max 3-5 retries.
Rate limit
Not counted
Variant C: System Throttle (code -1008)
"Request throttled by system-level protection. Reduce-only/close-position orders are exempt."
System overload from exceeding max concurrency. 100% failure. Retry with backoff and reduce concurrency. Applies to POST /fapi/v1/order, /batchOrders, /order/test.
Exception: reduce-only / close-position orders are not affected (closePosition=true, reduceOnly=true, LONG+SELL, SHORT+BUY).
Rate limit
Not counted (overload protection)
Variant D: Internal Error
"Internal error; unable to process your request. Please try again."
Internal processing failure. 100% failure. Safe to immediately retry.
Error Response Format
{ "code": -1121, "msg": "Invalid symbol." }
code
Specific error code (negative number)
msg
Human-readable error message
Common Error Codes
-1000
Unknown error processing the request
-1001
Disconnected - internal error
-1002
Unauthorized - not authorized for this request
-1003
Too many requests - rate limit exceeded
-1006
Unexpected response from message bus
-1007
Timeout waiting for backend server
-1008
Server overloaded with other requests
-1014
Unsupported order combination
-1015
Too many new orders
-1016
Server is shutting down
-1020
Unsupported operation
-1021
Invalid timestamp - outside recvWindow
-1022
Invalid signature
-1100
Illegal characters in parameter
-1101
Too many parameters sent
-1102
Mandatory parameter empty or missing
-1103
Unknown parameter sent
-1104
Not all sent parameters were read
-1105
Parameter was empty
-1106
Parameter sent when not required
-1111
Precision over maximum for this asset
-1116
Invalid orderType
-1117
Invalid side
-1121
Invalid symbol
-1128
Invalid timeInForce
-2010
New order rejected by exchange
-2011
Cancel rejected
-2013
Order does not exist
-2014
Bad API key format
-2015
Invalid API-key, IP, or permissions
Retry Logic Example
import time, requests def api_request_with_retry(url, max_retries=3): for attempt in range(max_retries): try: response = requests.get(url) response.raise_for_status() return response.json() except requests.exceptions.HTTPError as e: if e.response.status_code == 503: error_msg = e.response.json().get('msg', '') if 'Service Unavailable' in error_msg: wait_time = (2 ** attempt) * 0.2 time.sleep(wait_time) continue elif 'Unknown error' in error_msg: # Don't retry - verify order status first return None elif e.response.status_code == 429: retry_after = int(e.response.headers.get('Retry-After', 60)) time.sleep(retry_after) continue raise raise Exception(f"Max retries ({max_retries}) exceeded")