Error Codes
Overview
This document provides a comprehensive list of error codes that may be returned by the SynFutures API. Understanding these error codes will help you handle errors appropriately in your application.
HTTP Status Codes
2xx Success
200
OK - Request successful
201
Created - Resource created successfully
4xx Client Errors
400
Bad Request - Invalid request parameters or malformed request
401
Unauthorized - Invalid or missing API key, or signature verification failed
403
Forbidden - Access denied, insufficient permissions, or account restrictions
404
Not Found - Resource not found or endpoint does not exist
405
Method Not Allowed - HTTP method not supported for this endpoint
409
Conflict - Request conflicts with current state of the resource
422
Unprocessable Entity - Request validation failed
429
Too Many Requests - Rate limit exceeded
5xx Server Errors
500
Internal Server Error - Server encountered an unexpected error
502
Bad Gateway - Server received an invalid response from upstream
503
Service Unavailable - Server is temporarily unavailable
504
Gateway Timeout - Server did not receive a timely response from upstream
API Response Error Codes
General Error Codes (10000-19999)
10001
Request parameter error
Check request parameters and ensure they match the API specification
10002
Invalid API key
Verify your API key is correct and active
10003
Invalid signature
Check signature generation algorithm and parameters
10004
Request timestamp expired
Ensure your system clock is synchronized and timestamp is within valid range
10005
Invalid recv window
Check recv window parameter (should be between 1-60000)
10006
Invalid request ID
Ensure request ID is unique and properly formatted
10007
Request too frequent
Implement rate limiting to avoid exceeding request limits
10008
Service unavailable
Retry the request after a short delay
10009
System error
Contact support if the error persists
Authentication Error Codes (20000-29999)
20001
API key not found
Verify your API key is correct and has been created
20002
API key expired
Generate a new API key or renew the existing one
20003
API key permissions insufficient
Check API key permissions and ensure required scopes are enabled
20004
IP address not whitelisted
Add your IP address to the API key whitelist
20005
Signature verification failed
Verify signature generation and ensure all required parameters are included
20006
Timestamp too old
Ensure timestamp is within the valid time window
20007
Timestamp too new
Ensure timestamp is not in the future
20008
Invalid nonce
Ensure nonce is unique and properly formatted
Market Data Error Codes (30000-39999)
30001
Invalid symbol
Check symbol format and ensure it exists
30002
Invalid category
Use valid category: spot, linear, inverse, option
30003
Invalid interval
Use valid kline interval
30004
Invalid limit
Ensure limit is within allowed range
30005
Invalid start/end time
Check time format and ensure start < end
30006
Symbol not found
Verify symbol exists and is currently trading
30007
Market closed
Check market hours for the requested symbol
30008
Data not available
Requested data may not be available for the specified parameters
Trading Error Codes (40000-49999)
40001
Invalid order type
Use valid order type: Market, Limit, Stop, StopLimit
40002
Invalid side
Use valid side: Buy, Sell
40003
Invalid quantity
Check quantity format and ensure it meets minimum requirements
40004
Invalid price
Check price format and ensure it's within valid range
40005
Invalid time in force
Use valid time in force: GTC, IOC, FOK
40006
Insufficient balance
Ensure sufficient balance for the order
40007
Position size exceeded
Check position limits and risk parameters
40008
Order not found
Verify order ID exists and belongs to your account
40009
Order already filled
Order cannot be modified or cancelled as it's already filled
40010
Order already cancelled
Order has already been cancelled
40011
Invalid leverage
Check leverage value and ensure it's within allowed range
40012
Risk limit exceeded
Reduce position size or adjust risk parameters
40013
Market price not available
Use limit orders when market price is unavailable
40014
Trading suspended
Trading may be suspended for maintenance or other reasons
Account Error Codes (50000-59999)
50001
Account not found
Verify account exists and is accessible
50002
Account suspended
Contact support to resolve account suspension
50003
Account restricted
Check account restrictions and required verifications
50004
Insufficient permissions
Ensure account has required permissions for the operation
50005
Invalid account type
Use valid account type: UNIFIED, CONTRACT, SPOT
50006
Withdrawal disabled
Withdrawals may be disabled for security or compliance reasons
50007
Deposit disabled
Deposits may be disabled for maintenance or other reasons
50008
Transfer failed
Check transfer parameters and account status
System Error Codes (60000-69999)
60001
System maintenance
Wait for maintenance to complete
60002
Service overloaded
Retry request after a delay
60003
Database error
Contact support if error persists
60004
Network error
Check network connection and retry
60005
Configuration error
Contact support for configuration issues
60006
Internal processing error
Retry request or contact support
Error Response Format
All error responses follow this standard format:
{
"retCode": 10001,
"retMsg": "Request parameter error",
"result": {},
"time": "1640995200123"
}Response Fields
retCode
number
Error code number
retMsg
string
Human-readable error message
result
object
Empty object for error responses
time
string
Timestamp of the response
Error Handling Best Practices
1. Check Response Status
Always check the retCode field in the response:
if (response.retCode !== 0) {
console.error(`API Error ${response.retCode}: ${response.retMsg}`);
// Handle specific error
handleError(response.retCode, response.retMsg);
}2. Implement Retry Logic
For transient errors, implement retry logic:
async function apiCallWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
const response = await fetch(url, options);
const data = await response.json();
if (data.retCode === 0) {
return data;
}
// Retry for specific error codes
if (shouldRetry(data.retCode) && i < maxRetries - 1) {
await new Promise((resolve) =>
setTimeout(resolve, 1000 * (i + 1))
);
continue;
}
throw new Error(`API Error: ${data.retMsg}`);
} catch (error) {
if (i === maxRetries - 1) throw error;
await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)));
}
}
}
function shouldRetry(errorCode) {
const retryableErrors = [10008, 60001, 60002, 60004];
return retryableErrors.includes(errorCode);
}3. Log Errors Appropriately
Implement proper error logging:
function logError(errorCode, errorMessage, requestData) {
const errorLog = {
timestamp: new Date().toISOString(),
errorCode,
errorMessage,
requestData,
severity: getErrorSeverity(errorCode),
};
console.error("API Error:", errorLog);
// Send to monitoring service for critical errors
if (errorLog.severity === "critical") {
sendToMonitoring(errorLog);
}
}
function getErrorSeverity(errorCode) {
if (errorCode >= 60000) return "critical";
if (errorCode >= 40000) return "high";
if (errorCode >= 20000) return "medium";
return "low";
}4. User-Friendly Error Messages
Provide user-friendly error messages:
function getUserFriendlyMessage(errorCode) {
const errorMessages = {
10001: "Please check your request parameters",
10002: "Invalid API credentials",
10003: "Authentication failed",
40006: "Insufficient balance for this operation",
40012: "Position size exceeds risk limits",
50002: "Account is currently suspended",
60001: "System is under maintenance, please try again later",
};
return errorMessages[errorCode] || "An unexpected error occurred";
}Rate Limiting Errors
When rate limits are exceeded, you may receive:
{
"retCode": 10007,
"retMsg": "Request too frequent",
"result": {},
"time": "1640995200123"
}Rate Limit Headers
Check response headers for rate limit information:
const response = await fetch(url, options);
const rateLimitRemaining = response.headers.get("X-RateLimit-Remaining");
const rateLimitReset = response.headers.get("X-RateLimit-Reset");
console.log(`Remaining requests: ${rateLimitRemaining}`);
console.log(`Rate limit resets at: ${new Date(rateLimitReset * 1000)}`);Common Error Scenarios
1. Authentication Failures
{
"retCode": 20005,
"retMsg": "Signature verification failed",
"result": {},
"time": "1640995200123"
}Common causes:
Incorrect API secret
Wrong timestamp format
Missing required headers
Incorrect signature generation
2. Parameter Validation Errors
{
"retCode": 10001,
"retMsg": "Request parameter error",
"result": {},
"time": "1640995200123"
}Common causes:
Missing required parameters
Invalid parameter values
Incorrect parameter format
Out-of-range values
3. Trading Errors
{
"retCode": 40006,
"retMsg": "Insufficient balance",
"result": {},
"time": "1640995200123"
}Common causes:
Insufficient account balance
Position size limits exceeded
Risk parameter violations
Market conditions
Troubleshooting Guide
Step 1: Verify Request Format
Check HTTP method (GET, POST, etc.)
Verify endpoint URL
Ensure all required headers are present
Validate request body format (if applicable)
Step 2: Check Authentication
Verify API key is correct and active
Ensure signature is generated correctly
Check timestamp is within valid range
Verify IP address is whitelisted (if applicable)
Step 3: Validate Parameters
Check all required parameters are present
Verify parameter values are within valid ranges
Ensure parameter formats are correct
Check for any deprecated parameters
Step 4: Check Account Status
Verify account is active and not suspended
Check account permissions for the requested operation
Ensure sufficient balance (for trading operations)
Verify account type is correct
Step 5: Monitor System Status
Check for any ongoing maintenance
Verify system is operational
Check rate limit status
Monitor for any service disruptions
Support
If you continue to experience issues:
Check the Quick Start Guide for basic setup
Review individual API documentation files
Verify your implementation matches the examples
Contact support with specific error codes and request details
Error Code Updates
This error code list is updated regularly. Always refer to the latest version for the most current error codes and descriptions.
Last updated