頻率與配額

WebSocket 行情推送會按賬號、連接、訂閲標的、訂閲類型和行情權限進行配額與權限校驗。配額用於保護長連接服務穩定性，也用於確保不同權限檔位的用户只能訂閲其已開通的行情能力。

INFO

具體配額數量與賬號類型、行情權限、產品套餐、市場和品類有關。本文說明配額的計算口徑和客户端處理建議，不提供固定數值限制。請以賬號實際權限、接口返回和產品配置為準。

配額類型

類型	說明	客户端建議
連接配額	限制同一賬號或同一應用可同時保持的 WebSocket 長連接數量。超過限制時，新連接、登錄鑑權或後續訂閲可能失敗。	複用連接承載多個標的和多個數據類型，避免為每個標的單獨建立連接。
訂閲配額	限制同一賬號當前可保持的訂閲項總量。訂閲項通常由“標的 + 數據類型”組成，K 線還會包含週期和復權方式。	頁面退出、標的切換或不再展示某類行情時，及時發送反訂閲請求釋放配額。
權限配額	行情權限決定是否可訂閲某市場、品類和數據深度，例如買賣盤檔數、深度擺盤、經紀隊列等。	訂閲前確認用户已開通對應市場與行情檔位；收到權限錯誤時引導用户開通或降級訂閲。
頻率限制	服務端可能限制鑑權、訂閲、反訂閲、重連等控制消息的發送頻率。	合併批量訂閲請求，避免在短時間內反覆訂閲和反訂閲同一標的。

連接配額

WebSocket 是長連接能力，連接數本身也會消耗服務端資源。客户端應儘量採用“少連接、多訂閲”的方式：

同一業務頁面優先複用一個 WebSocket 連接。
同一連接內可以訂閲多個標的和多個行情類型。
不建議因為標的數量增加而線性增加連接數。
多窗口、多設備同時在線時，應考慮賬號級連接上限可能被共同佔用。
連接斷開後應重新連接、重新登錄鑑權並重新訂閲，不要假設舊連接上的訂閲狀態仍然有效。

如果客户端需要同時運行在多個頁面或多個進程中，建議在應用層統一管理連接，避免每個組件各自創建 WebSocket。

訂閲配額

訂閲配額按賬號維度統計當前仍然有效的訂閲項。一次訂閲請求中，不同數據類型會分別佔用訂閲資源，例如：

quote：基礎報價訂閲。
order_book：買賣盤訂閲。
ticker：逐筆成交訂閲。
kline：K 線訂閲，通常還會按 period 和 adjust 區分不同訂閲項。

服務端內部會使用賬號維度的總配額進行校驗。該總配額在後端鏈路中可稱為 uid_total_quota，表示當前用户可使用的全局訂閲總額度。它由登錄態、賬號權限或上游網關注入，不是客户端應自行填寫或偽造的公開請求字段。

WARNING

不要依賴固定的公開配額數字，也不要假設某一類訂閲一定不佔用配額。不同環境、權限檔位和服務端版本的計數規則可能不同，尤其是 K 線是否計入總訂閲配額，應以生產環境實際返回和產品規則為準。

配額超限錯誤

當新增訂閲會超過賬號可用訂閲總額度時，訂閲請求會失敗。若網關直接透傳訂閲響應，常見響應語義如下：

字段	說明
`id`	對應客户端請求中的 `id`，用於匹配請求與響應。
`code`	結果碼，`0` 表示成功。
`message`	錯誤說明。

配額超限時，服務端可能返回：

json

{
  "id": "sub-001",
  "code": 4,
  "message": "sub quota exceeded, max=..."
}

其中 code = 4 表示訂閲配額不足或超過最大訂閲數。客户端收到該錯誤後，不應立即高頻重試；應先減少當前訂閲項，或提示用户升級權限/套餐後再重試。

INFO

公開 WebSocket 網關可能會對錯誤響應做包裝或翻譯。請以實際返回字段為準，但排查配額問題時可以重點關注“quota exceeded”“sub quota exceeded”以及錯誤碼 4。

買賣盤深度與權限

order_book 買賣盤訂閲不僅受訂閲總量限制，還受行情權限檔影響。不同市場、品類和權限檔位可能返回不同深度：

LV1 權限通常只能獲得基礎檔位或有限深度。
LV2/LV3 等更高權限可能支持更多檔位或深度擺盤。
部分港股品類可能同時具備經紀隊列能力，對應推送 BROKER_QUEUE。
未開通對應市場或深度權限時，訂閲可能失敗，或只能返回較低檔位的數據。

因此，客户端不應僅根據訂閲請求是否包含 order_book 來假設一定能收到完整深度擺盤。展示層應根據實際推送內容、數組長度和字段缺省情況進行兼容處理。

逐筆成交批量推送

ticker 逐筆成交可能按批次合併推送，而不是每一筆成交都單獨發送一條 WebSocket 消息。客户端應按 ticker_list 數組處理一批成交記錄：

不要假設一條 TICKER 消息只包含一筆成交。
應按 sequence、time_ms 等字段做去重、排序或增量合併。
UI 渲染應做節流，避免每收到一批數據就觸發高成本全量重繪。
如果斷線期間需要補齊最新成交，可在重連後結合 REST 逐筆成交接口查詢。

訂閲與反訂閲最佳實踐

合併請求

儘量把同一時刻需要訂閲的標的和類型合併到一次請求中發送。例如頁面初始化時，一次性訂閲當前可見列表的 quote，而不是為每個標的各發送一次訂閲請求。

按可見範圍訂閲

對於大列表、滾動表格或自選股分組，建議只訂閲當前頁面需要展示的標的：

用户切換分組時，反訂閲舊分組不再展示的標的。
列表滾動時，可以按窗口範圍增量訂閲和反訂閲。
後台頁面或隱藏 Tab 可降低訂閲規模，必要時只保留關鍵標的。

及時釋放配額

當用户關閉頁面、切換標的、取消關注或不再需要某類行情時，應主動發送 unsubscribe：

反訂閲成功後，對應訂閲項才會釋放配額。
同一賬號在其他連接或設備上仍持有相同訂閲時，賬號級配額可能不會立即減少到 0。
連接異常斷開後，服務端會清理離線會話，但客户端不應依賴清理延遲來釋放配額。

避免訂閲抖動

以下行為容易觸發頻率限制或造成配額抖動：

用户每輸入一個字符就重新訂閲搜索結果。
在短時間內對同一標的反覆訂閲和反訂閲。
網絡不穩定時多個連接同時自動重連並全量重訂閲。
因 UI 重渲染導致重複發送相同訂閲請求。

建議在客户端加入防抖、去重和狀態機：只有當目標訂閲集合發生變化時，才發送增量訂閲或反訂閲請求。

重連後分批恢復

斷線重連後需要重新登錄鑑權並恢復訂閲。若訂閲集合較大，建議：

先恢復頁面當前可見或業務最關鍵的標的。
再分批恢復其他標的。
每批請求之間保留短暫間隔，並處理失敗重試。
對配額超限、權限不足、標的無效等錯誤做分類處理，不要無限重試。

降級策略

當訂閲失敗或配額不足時，客户端可以按業務重要性降級：

優先保留當前屏幕可見標的。
優先保留 quote 基礎報價，減少 order_book、ticker 或多週期 kline 訂閲。
買賣盤深度權限不足時，降級展示可用檔位或提示用户開通權限。
對低優先級標的改用 REST 低頻輪詢。

排查建議

遇到配額或頻率相關問題時，可以按以下順序排查：

確認 WebSocket 已完成登錄鑑權。
檢查訂閲請求中的標的代碼、數據類型、K 線週期和復權方式是否有效。
檢查是否存在重複訂閲、未反訂閲或多個頁面共享賬號佔用配額。
查看訂閲響應中的 id、code 和 message，重點關注 code = 4 或 quota 相關提示。
檢查用户是否具備對應市場、品類和買賣盤深度權限。
對大批量訂閲場景，降低單批訂閲數量並增加重試退避。

頻率與配額 ​

配額類型 ​

連接配額 ​

訂閲配額 ​

配額超限錯誤 ​

買賣盤深度與權限 ​

逐筆成交批量推送 ​

訂閲與反訂閲最佳實踐 ​

合併請求 ​

按可見範圍訂閲 ​

及時釋放配額 ​

避免訂閲抖動 ​

重連後分批恢復 ​

降級策略 ​

排查建議 ​

相關文檔 ​