跳轉到主要內容
本頁面描述了 TickDB 如何在 REST 和 WebSocket API 中報告錯誤。 它解釋了錯誤格式、常見狀態碼以及如何正確處理它們。 有關特定端點的錯誤詳情，請參閱按端點分類的錯誤代碼。

​
REST API 錯誤格式

REST API 錯誤返回 HTTP 狀態碼和 JSON 響應體。

​
示例：身份驗證錯誤 (401)

{
  "success": false,
  "error": "Invalid or inactive API key",
  "code": 401
}

​
示例：速率限制錯誤 (429)

速率限制響應可能包含額外字段以幫助客戶端恢復或升級。 
{
  "success": false,
  "error": "Rate limit exceeded",
  "code": 429,
  "limit": 60,
  "used": 60,
  "reset_at": 1700000000,
  "plan": "free",
  "upgrade_to": "standard"
}

​
WebSocket 錯誤格式

WebSocket 錯誤分為兩類：
  1. 連接級錯誤（HTTP 狀態碼如 401、403、429）
  2. 消息級錯誤（自定義錯誤代碼）

​
示例：消息級錯誤

{
  "cmd": "subscribe",
  "code": 2001,
  "message": "symbols parameter is required"
}

​
常見 HTTP 狀態碼

HTTP 狀態描述典型原因
200成功請求成功
400錯誤請求缺少或無效的參數
401未授權缺少、無效或已停用的 API 密鑰
403禁止訪問此端點或市場的權限被拒絕
404未找到端點或交易品種未找到
429請求過多超出速率限制
500內部服務器錯誤意外的服務器錯誤
502網關錯誤上游服務錯誤
503服務不可用臨時服務中斷

​
常見 WebSocket 錯誤代碼

WebSocket 錯誤代碼是自定義代碼，不是 HTTP 狀態碼。
代碼描述典型原因
2001無效的消息格式或命令JSON 格式錯誤、未知命令或缺少字段
2003深度訂閱不可用深度頻道暫時禁用
2004交易訂閱不可用交易頻道暫時禁用

​
錯誤處理最佳實踐

  • 在解析響應之前始終檢查 HTTP 狀態碼。
  • 對於 429 錯誤，在 reset_at 之前等待後再重試。
  • 不要立即重試 500 錯誤；使用指數退避。
  • 在本地驗證請求參數以避免 400 錯誤。
  • 對於 WebSocket API：
    • 確保消息是有效的 JSON
    • 始終包含必需字段（cmd、channel、symbols）

​
相關文檔

  • 身份驗證 – API 密鑰使用和權限
  • 數據規範 – 交易品種格式和市場定義
  • 按端點分類的錯誤代碼 – 每個 API 端點的詳細錯誤消息