❌ Why API Error Codes Matter
When building applications that interact with cryptocurrency exchanges, you will inevitably encounter API errors. Understanding these error codes is essential for building robust, reliable applications. Without proper error handling, your trading bot could fail silently, miss trades, or worse — place unintended orders.
This guide covers:
- HTTP status codes — The foundation of API error handling.
- Exchange-specific error codes — Detailed errors from Binance, OKX, Bybit, and KuCoin.
- Error handling strategies — How to handle each error type effectively.
- Debugging tips — How to identify and fix common issues.
Never ignore API errors. Always log them, understand them, and implement appropriate handling. Ignoring errors is the number one cause of trading bot failures.
🌐 HTTP Status Codes
HTTP status codes are the first level of error indication. They tell you whether your request was successful, and if not, what category of error occurred.
| Status Code | Meaning | Common Causes | How to Handle |
|---|---|---|---|
| 200 | OK | Request successful | Process the response |
| 400 | Bad Request | Invalid parameters, malformed request | Check parameter values, format, and types |
| 401 | Unauthorized | Missing or invalid API key, signature error | Verify API key, signature, and permissions |
| 403 | Forbidden | IP not whitelisted, insufficient permissions | Check IP whitelist, API key permissions |
| 404 | Not Found | Endpoint URL is incorrect | Verify the endpoint URL |
| 429 | Too Many Requests | Rate limit exceeded | Wait and retry with exponential backoff |
| 5xx | Server Error | Exchange server issue | Retry with exponential backoff |
For 429 and 5xx errors, implement exponential backoff — wait 1s, then 2s, then 4s, then 8s before retrying. This prevents overwhelming the server and gives you the best chance of success.
🔵 Binance API Error Codes
Binance uses a combination of HTTP status codes and exchange-specific error codes. The most common ones are listed below.
| Error Code | Message | Cause | Solution |
|---|---|---|---|
| -1021 | Timestamp out of sync | Your system time is off | Synchronize system time via NTP |
| -1022 | Signature invalid | Incorrect signature generation | Check signature algorithm and order |
| -1121 | Invalid symbol | Symbol doesn't exist | Verify symbol is correct |
| -1128 | Invalid quantity | Quantity below min or not step-sized | Check exchange filters for the symbol |
| -1130 | Invalid price | Price below min or not tick-sized | Check exchange filters for the symbol |
| -2010 | Order failed | Insufficient balance, order rejected | Check balance, parameters, market conditions |
| -2013 | Order does not exist | Order ID not found | Verify order ID before querying |
| -2014 | API key format invalid | Incorrect API key format | Check API key length and format |
| -2015 | Invalid API key | API key doesn't exist or is disabled | Verify API key is active and correct |
The -1021 error is extremely common. Always synchronize your system time using NTP (sudo ntpdate -u pool.ntp.org). Also, consider using the recvWindow parameter (set to 5000ms) to allow for minor time differences.
🔴 OKX API Error Codes
OKX uses a structured error response with a code field. Here are the most common ones.
| Error Code | Message | Cause | Solution |
|---|---|---|---|
| 30001 | Invalid request | Malformed request | Check request format and parameters |
| 30008 | Insufficient balance | Not enough funds | Check balance before placing orders |
| 30009 | Invalid symbol | Symbol doesn't exist | Verify symbol is correct |
| 30010 | Invalid order size | Quantity below min or not step-sized | Check exchange filters for the symbol |
| 30011 | Invalid order price | Price below min or not tick-sized | Check exchange filters for the symbol |
| 30012 | Order not found | Order ID not found | Verify order ID before querying |
| 30013 | Order already canceled | Order already canceled | Check order status before canceling |
| 30014 | Order already filled | Order already filled | Check order status before canceling |
| 30015 | API key not found | API key doesn't exist | Verify API key is active and correct |
🟣 Bybit API Error Codes
Bybit uses a retCode field in its API responses. Here are the most common codes.
| Error Code | Message | Cause | Solution |
|---|---|---|---|
| 10001 | Invalid request | Malformed request | Check request format and parameters |
| 10002 | Invalid API key | API key doesn't exist or is disabled | Verify API key is active and correct |
| 10003 | Invalid signature | Incorrect signature generation | Check signature algorithm and order |
| 10004 | Timestamp out of sync | Your system time is off | Synchronize system time via NTP |
| 10005 | IP not whitelisted | IP not in whitelist | Add IP to whitelist in API settings |
| 11001 | Insufficient balance | Not enough funds | Check balance before placing orders |
| 11002 | Invalid symbol | Symbol doesn't exist | Verify symbol is correct |
| 11003 | Invalid quantity | Quantity below min or not step-sized | Check exchange filters for the symbol |
| 11004 | Invalid price | Price below min or not tick-sized | Check exchange filters for the symbol |
| 11005 | Order not found | Order ID not found | Verify order ID before querying |
🟡 KuCoin API Error Codes
KuCoin uses a code field in its API responses. Here are the most common ones.
| Error Code | Message | Cause | Solution |
|---|---|---|---|
| 400001 | Invalid request | Malformed request | Check request format and parameters |
| 400002 | Invalid API key | API key doesn't exist or is disabled | Verify API key is active and correct |
| 400003 | Invalid signature | Incorrect signature generation | Check signature algorithm and order |
| 400004 | Timestamp out of sync | Your system time is off | Synchronize system time via NTP |
| 400005 | IP not whitelisted | IP not in whitelist | Add IP to whitelist in API settings |
| 400006 | Insufficient balance | Not enough funds | Check balance before placing orders |
| 400007 | Invalid symbol | Symbol doesn't exist | Verify symbol is correct |
| 400008 | Invalid quantity | Quantity below min or not step-sized | Check exchange filters for the symbol |
| 400009 | Invalid price | Price below min or not tick-sized | Check exchange filters for the symbol |
| 400010 | Order not found | Order ID not found | Verify order ID before querying |
🛡️ Error Handling Strategies
Here's a systematic approach to handling API errors in your applications.
-
1
Validate inputs before sending
Check symbol validity, quantity limits, price precision, and balance before making the request.
-
2
Check HTTP status code
Handle 4xx (client errors) and 5xx (server errors) differently. 4xx indicates a problem with your request; 5xx indicates a problem on the exchange side.
-
3
Read the error message
The error message often contains specific details about what went wrong. Use this to diagnose the issue.
-
4
Implement retry logic with exponential backoff
For 429 and 5xx errors, retry with increasing delays. Use a maximum retry limit to avoid infinite loops.
-
5
Log all errors
Log error codes, messages, timestamps, and request details for debugging and monitoring.
-
6
Monitor error rates
Set up monitoring to alert you if error rates exceed a threshold. This helps you detect issues early.
Implement a retry function with exponential backoff: retry_count = 0; while retry_count < max_retries: try: make_request(); break; except APIError: wait = min(60, 2^retry_count); time.sleep(wait); retry_count += 1
🔍 Debugging Tips
Here are practical tips for debugging API errors.
- Check your system time: Many errors (-1021, 400004) are caused by time drift. Synchronize with NTP.
- Verify your signature: Ensure your signature generation matches the exchange's requirements (algorithm, order of parameters).
- Check API key permissions: Ensure your API key has the required permissions (Read, Trade, etc.).
- Test with a REST client: Use tools like Postman or curl to test your requests before implementing them in code.
- Read the documentation: Always refer to the exchange's official API documentation for specific error codes and requirements.
- Enable verbose logging: Log full request and response details to help diagnose issues.
When debugging, always check the full error response — not just the error code. The message often contains the specific reason for the error, which is essential for fixing it.