錯誤碼

WebSocket 行情推送涉及兩類錯誤碼，分別來自不同層級：

兩類錯誤碼互相獨立，碼值範圍不重疊，可通過數值範圍直接區分。

通道錯誤碼

通道錯誤發生在請求到達業務邏輯之前，由 WebSocket 網關或鑑權服務返回。

json

{
  "id": "req-001",
  "code": 4002,
  "msg": "auth_failed"
}

注意：字段名為 msg，與訂閲響應的 message 字段不同。

code	含義	常見原因	處理建議
`4000`	請求格式錯誤	發送的幀結構不符合協議，如 JSON 格式有誤、`action` 字段為空。	檢查請求幀格式，修復後重新發送。
`4001`	尚未完成鑑權	在鑑權成功之前發送了業務請求。	先完成 Auth 鑑權，收到 `session_id` 後再發送業務請求。
`4002`	鑑權失敗	`credential_id` 不存在、簽名驗證不通過、Bearer Token 已過期或無效。	檢查憑證和簽名邏輯；OAuth2 場景需先刷新 Token 再重新建立連接。
`4003`	權限不足	當前憑證的授權範圍（scope）不包含所請求的接口權限。	確認所用憑證是否已授權該接口；如使用 OAuth2，檢查授權時申請的 scope。
`4004`	接口不存在	`action` 填寫有誤，或請求了服務端未開放的接口。	核對接口文檔，確認 `action` 名稱拼寫正確。
`5000`	服務內部錯誤	服務端處理請求時發生意外異常。	可聯繫服務端排查；不建議自動重試。
`5002`	網關錯誤	服務端網絡異常，請求未能送達後端。	稍後重試；持續出現請檢查網絡環境或聯繫服務端。
`5003`	服務暫時不可用	服務端負載過高，暫時無法處理新請求。	等待片刻後重試，建議加退避策略。
`5004`	請求超時	服務端處理超時，未能在規定時間內返回結果。	稍後重試；持續超時請聯繫服務端排查。

訂閲響應碼僅出現在訂閲（subscribe）和反訂閲（unsubscribe）請求的響應中，由業務層處理後返回。

json

{
  "id": "sub-001",
  "code": 0,
  "message": "success"
}

注意：字段名為 message，與通道錯誤的 msg 字段不同。

成功示例：

json

{
  "id": "sub-001",
  "code": 0,
  "message": "success"
}

失敗示例：

json

{
  "id": "sub-002",
  "code": 4,
  "message": "sub quota exceeded, max=100"
}

code	含義	常見原因	處理建議
`0`	成功	訂閲、反訂閲或會話清理請求處理成功。	繼續接收推送，或更新本地訂閲狀態。
`1`	必要會話信息缺失	未完成鑑權就發起訂閲；連接會話異常；網關未能建立有效用户會話。	重新建立 WebSocket 連接，先完成登錄鑑權，再重新訂閲。
`2`	不支持的操作類型	`action` 填寫錯誤，或使用了服務端不支持的動作。	檢查 `action` 是否為 `subscribe` 或 `unsubscribe`。
`3`	系統異常	服務端進行訂閲配額檢查時依賴服務暫時不可用。	按退避策略稍後重試；如果持續出現，請聯繫技術支持並提供請求 ID、時間和返回內容。
`4`	訂閲配額不足	當前賬號的訂閲數量超過上限。	減少訂閲標的或數據類型；先反訂閲不再使用的標的；確認賬號行情權限和配額。
`5`	K 線週期參數非法	`kline.period` 不在支持範圍內，或週期格式不正確。	按訂閲與反訂閲中支持的 K 線週期重新傳參。

TIP

收到非 0 響應時，不應把該請求視為已生效。客户端應保持本地訂閲狀態與服務端響應一致：只有在訂閲成功後才標記為已訂閲，只有在反訂閲成功後才移除本地訂閲記錄。