When integrating with trading platforms, developers often encounter various API error codes. Understanding these codes is crucial for building robust applications and ensuring smooth trading operations. This guide provides a comprehensive overview of common error categories, their meanings, and practical solutions.
Understanding API Error Structure
API errors typically consist of two parts: an error code and a corresponding error message. The code represents a general category, while the message provides specific details about what went wrong.
Here's a typical error response format:
{
"code": -1121,
"msg": "Invalid symbol."
}Server and Network Issues (10xx Series)
-1000: Unknown Error
An unspecified error occurred. This generic error often resolves with a simple retry.
-1001: Disconnected
The connection was interrupted. This is usually an internal issue that typically resolves when you reconnect.
-1002: Unauthorized
Your request lacked proper authorization. Verify that your API keys have the correct permissions configured.
-1003: Too Many Requests
You've exceeded the rate limits. The system prevents excessive requests to maintain stability. Consider using WebSocket streams for real-time updates instead of frequent API polling.
-1006: Unexpected Response
The server returned a message that doesn't conform to expected formats. The order status remains unknown when this occurs.
-1007: Timeout
The backend service didn't respond in time. The order status is uncertain when this error appears.
-1008: Server Busy
The trading server is temporarily overloaded. Wait a few minutes before retrying your request.
-1013: Invalid Message
The API rejected your request before it reached the matching engine. Check for issues with your request parameters or filters.
Request Parameter Problems (11xx Series)
-1100: Illegal Characters
Your request contains invalid characters in one or more parameters. Ensure all values fall within the acceptable character range.
-1101: Too Many Parameters
You've sent more parameters than the endpoint expects. Review the API documentation for required and optional parameters.
-1102: Missing Mandatory Parameters
A required parameter was not provided, was empty, or was malformed. Double-check that all necessary fields are included and properly formatted.
-1103: Unrecognized Parameter
Your request contains a parameter that the API doesn't recognize. This often happens with typos or using outdated parameter names.
-1104: Redundant Parameters
You've included parameters that weren't processed. The API read some parameters but ignored others you sent.
For comprehensive API solutions and real-time monitoring tools, explore advanced developer resources.
-1105: Empty Parameter
A parameter was provided but contained no value. Ensure all parameters have appropriate values.
-1106: Unnecessary Parameter
You included a parameter when it wasn't required for this specific request type.
-1108: Parameter Overflow
A numeric parameter exceeds the maximum allowed value. Reduce the value to fit within acceptable limits.
-1111: Excessive Precision
A parameter contains more decimal places than allowed. Round the value to the appropriate precision.
-1121: Invalid Symbol
The trading pair specified doesn't exist or isn't recognized. Verify the symbol format matches exchange requirements.
Order Management Errors
-2010: New Order Rejected
The system rejected your new order request. This could be due to insufficient funds, invalid parameters, or market conditions.
-2011: Cancel Order Rejected
Your request to cancel an order was not processed. The order might already be filled, cancelled, or nonexistent.
-2013: Nonexistent Order
The order you referenced doesn't exist in the system. Verify the order ID or client order ID.
-2014: Invalid API Key Format
Your API key doesn't conform to the expected format. Generate a new key if necessary.
-2015: API Key Permission Issues
Your API key might not exist, the request might come from an unapproved IP address, or the key might lack required permissions.
Frequently Asked Questions
What should I do first when encountering an API error?
Always check the error code and message first. For network-related errors (-1000 to -1008), simply retrying the request often resolves the issue. For parameter errors (-1100 series), verify your request against the API documentation.
How can I avoid rate limiting errors?
Implement proper request throttling in your application. Use WebSocket streams for real-time data instead of repeatedly polling REST endpoints. Monitor your request weights and stay within the published limits.
Why does my order keep getting rejected?
Order rejections can occur for various reasons: insufficient balance, invalid symbol, incorrect price precision, or market closure. Check the specific error message for details and verify your order parameters against the exchange's filters.
What's the difference between -1013 and filter failures?
Error -1013 indicates the API rejected your request before it reached the matching engine, usually due to fundamental issues with your request structure. Filter failures occur when your order parameters don't pass the exchange's trading rules, such as price filters or lot size requirements.
How do I handle authentication errors?
Verify your API key permissions, check that your system clock is synchronized (for signature generation), and ensure you're sending requests from whitelisted IP addresses. Get advanced authentication methods for enterprise applications.
What should I do when encountering 'server busy' errors?
Implement exponential backoff in your retry logic. Wait progressively longer between retries (e.g., 1 second, 2 seconds, 4 seconds) to avoid overwhelming the server during high-load periods.
Order Filter Failures
Exchange APIs implement various filters to ensure order validity:
PRICE_FILTER: Your order price doesn't meet the minimum, maximum, or step size requirements for the trading pair.
LOT_SIZE: The order quantity falls outside acceptable limits or doesn't conform to the required step size.
MIN_NOTIONAL: The total order value (price × quantity) is below the minimum allowed value for the pair.
MARKET_LOT_SIZE: Similar to LOT_SIZE but specifically applies to market orders.
MAX_NUM_ORDERS: You've exceeded the maximum number of open orders allowed for this symbol.
TRAILING_DELTA: The trailing delta value falls outside the acceptable range for this order type.
Best Practices for Error Handling
Implement robust error handling in your trading application:
- Always check response codes and messages
- Implement appropriate retry logic for transient errors
- Log errors with sufficient context for debugging
- Monitor error rates to detect integration issues
- Stay updated with API changes and new error codes
Proper error handling ensures your application remains stable and provides better user experiences when unexpected situations occur.