Documentation Index
Fetch the complete documentation index at: https://docs.tickdb.ai/llms.txt
Use this file to discover all available pages before exploring further.
本文檔面向 API 用戶，說明接口返回的錯誤碼含義及處理建議。
響應格式
HTTP API
{
"code": 0,
"message": "success",
"data": { ... }
}
WebSocket
{
"cmd": "subscribe",
"code": 0,
"message": "success",
"data": { ... }
}
錯誤碼速查表
| 錯誤碼 | 含義 | 處理建議 |
|---|
| 0 | 成功 | - |
| 1001 | API Key 無效或已過期 | 檢查 API Key 是否正確 |
| 1002 | 未提供 API Key | 在請求頭添加 X-API-Key |
| 1003 | IP 不在白名單 | 聯繫管理員添加 IP |
| 1004 | 權限不足 | 升級套餐或聯繫管理員 |
| 2001 | 參數錯誤 | 檢查請求參數 |
| 2002 | 交易品種不存在 | 使用 /v1/symbols/available 查詢可用品種 |
| 2003 | 時間範圍無效 | 檢查 start_time/end_time 參數 |
| 2004 | 請求數量超限 | 減少 limit 參數值 |
| 3001 | 請求頻率超限 | 降低請求頻率，參考 Retry-After 頭 |
| 3002 | 配額已用盡 | 等待配額重置或升級套餐 |
| 3003 | 連接數超限 | 關閉多餘連接 |
| 3004 | 訂閱數超限 | 取消部分訂閱 |
| 4001 | 未知命令 | 檢查 WebSocket 消息的 cmd 字段 |
| 4002 | 消息格式錯誤 | 檢查 JSON 格式 |
| 4003 | 深度訂閱暫不可用 | 使用 HTTP API 獲取深度數據 |
| 4004 | 成交訂閱暫不可用 | 使用 HTTP API 獲取成交數據 |
| 5000 | 服務器內部錯誤 | 稍後重試，如持續請聯繫支持 |
| 5001 | 數據源不可用 | 稍後重試 |
| 5002 | 服務暫時不可用 | 稍後重試 |
詳細說明
認證錯誤 (1xxx)
1001 - API Key 無效或已過期
{
"code": 1001,
"message": "Invalid or expired token"
}
- API Key 輸入錯誤
- API Key 已被禁用
- API Key 已過期
解決：檢查 API Key 是否正確，或聯繫管理員確認狀態。
1002 - 未提供 API Key
{
"code": 1002,
"message": "Token is required"
}
X-API-Key: your_api_key，或在 WebSocket URL 中添加 ?api_key=your_api_key。
1003 - IP 不在白名單
{
"code": 1003,
"message": "IP address not in whitelist"
}
1004 - 權限不足
{
"code": 1004,
"message": "Permission denied"
}
參數錯誤 (2xxx)
2001 - 參數錯誤
{
"code": 2001,
"message": "Invalid parameter: symbol is required"
}
2002 - 交易品種不存在
{
"code": 2002,
"message": "Symbol not found"
}
GET /v1/symbols/available 獲取可用品種列表。
2003 - 時間範圍無效
{
"code": 2003,
"message": "Invalid time range"
}
- start_time 大於 end_time
- 時間格式錯誤
- 時間範圍超出限制
解決：使用 Unix 毫秒時間戳，確保 start_time < end_time。
2004 - 請求數量超限
{
"code": 2004,
"message": "Request limit exceeded"
}
limit 參數值（通常最大 1000）。
限流錯誤 (3xxx)
3001 - 請求頻率超限
{
"code": 3001,
"message": "Rate limit exceeded"
}
Retry-After 頭，指示等待秒數。
解決：
- 降低請求頻率
- 使用 WebSocket 訂閱替代輪詢
- 升級套餐獲取更高配額
3002 - 配額已用盡
{
"code": 3002,
"message": "Quota exhausted"
}
3003 - 連接數超限
{
"code": 3003,
"message": "Connection limit exceeded"
}
- 調用
GET /v1/connections 查看當前連接
- 調用
DELETE /v1/connections/:id 關閉多餘連接
3004 - 訂閱數超限
{
"code": 3004,
"message": "Subscription limit exceeded"
}
WebSocket 錯誤 (4xxx)
4001 - 未知命令
{
"cmd": "unknown",
"code": 4001,
"message": "Unknown command"
}
cmd 字段，支持的命令：subscribe、unsubscribe、ping。
4002 - 消息格式錯誤
{
"cmd": "subscribe",
"code": 4002,
"message": "Invalid message format"
}
4003 / 4004 - 訂閱暫不可用
{
"cmd": "subscribe",
"code": 4003,
"message": "Depth subscriptions temporarily unavailable",
"data": {
"channel": "depth",
"suggestion": "Use HTTP API /v1/market/depth for current depth data"
}
}
服務錯誤 (5xxx)
5000 - 服務器內部錯誤
{
"code": 5000,
"message": "Internal server error"
}
5001 - 數據源不可用
{
"code": 5001,
"message": "Data source unavailable"
}
5002 - 服務暫時不可用
{
"code": 5002,
"message": "Service temporarily unavailable"
}
錯誤處理示例
JavaScript
async function fetchTicker(symbol) {
const response = await fetch(`/v1/market/ticker/${symbol}`, {
headers: { 'X-API-Key': API_KEY }
});
const data = await response.json();
if (data.code !== 0) {
switch (data.code) {
case 1001:
case 1002:
throw new Error('認證失敗，請檢查 API Key');
case 2002:
throw new Error(`交易品種 ${symbol} 不存在`);
case 3001:
const retryAfter = response.headers.get('Retry-After') || 60;
console.log(`請求過快，${retryAfter} 秒後重試`);
break;
default:
throw new Error(data.message);
}
}
return data.data;
}
Python
import requests
def fetch_ticker(symbol, api_key):
response = requests.get(
f'/v1/market/ticker/{symbol}',
headers={'X-API-Key': api_key}
)
data = response.json()
if data['code'] != 0:
if data['code'] in [1001, 1002]:
raise Exception('認證失敗，請檢查 API Key')
elif data['code'] == 2002:
raise Exception(f'交易品種 {symbol} 不存在')
elif data['code'] == 3001:
retry_after = response.headers.get('Retry-After', 60)
print(f'請求過快，{retry_after} 秒後重試')
else:
raise Exception(data['message'])
return data['data']
如有疑問，請聯繫技術支持。