速率限制規則（UTA）

UTA RESTful 速率限制

1.資源池介紹

平台採用根據不同業務場景劃分多個限頻池（Rate Limit Pool）的方案，對 API 接口調用進行限頻管理。

每個 API 接口均歸屬於指定的限頻池，並在接口文檔中標註對應的限頻池（Rate Limit Pool）。

使用者調用 API 時，系統將根據接口所屬限頻池及使用者對應的限頻配額進行請求頻率控制。

目前 API 限頻池主要分為以下兩類：

1.1 私有限頻池（Private Rate Limit Pool）

私有限頻池適用於需要登錄認證的 API 接口，因此限頻規則基於 UID 維度進行管理。

1.2 公有限頻池（Public Rate Limit Pool）

公有限頻池適用於無需身份認證即可調用的 API 接口，因此限頻規則基於 IP 維度進行管理。
若需大量使用公共接口，建議優先使用 WebSocket 接口（若該接口支援）以取代 REST 接口。為避免 IP 速率限制，您可採用以下方式：
使用一台伺服器綁定多個 IP 位址（IPv4 或 IPv6）。
使用不同的 IP 位址進行請求。

2. 權重

2.1 權重規則介紹

當用戶請求任何 API 時，此界面的權重會每 1s (從用戶第一次請求的到達時間開始) 扣除並更新一次。有關各接口的具體速率限制權重，可參閱相關介面下的速率限制規定。

若在 1 秒內任何資源池的配額耗盡（即超過速率限制），就會傳回 http code:429, error code:429000 的錯誤代碼，並在回應標頭中顯示可再次發送請求的時間。用戶在此期間必須暫停存取，待資源配額重置後方可繼續。

例如：
當用戶00123的 VIP 為 5 時，他/她的「總限頻配額」為 700/s。
每個「根据 ID 批量撤單」的配額消耗量為 4。第一次批量撤單後，用戶的剩餘幣幣配額為 696，第二次批量撤單後，剩餘配額為 692，以此類推。

如果配額在 1 秒內未使用完畢，當下一個週期來臨時，即時資源池配額將被重設，並回到 700 的配額限制。

2.2 HTTP Header 查詢

每個請求返回的 HTTP Header 將包含下列資訊：總資源池配額、資源池剩餘配額、資源池配額重設倒數（毫秒）。

同上述用戶00123的例子，當客戶第一次批量撤單後：

"gw-ratelimit-limit":700
"gw-ratelimit-remaining"：696
"gw-ratelimit-reset": 489 （單位ms）

3. VIP 等級限頻額度分配

不同 VIP 等級的使用者，在各限頻池中會獲得對應的限頻配額。

等級/限頻池	統一帳戶（包含WebSocket下撤单）	管理 (UTA REST)（即将上线）	公眾
VIP0	300/s	300/s	2000/30s
VIP1	400/s	400/s	2000/30s
VIP2	450/s	450/s	2000/30s
VIP3	500/s	500/s	2000/30s
VIP4	750/s	750/s	2000/30s
VIP5	900/s	900/s	2000/30s
VIP6	1100/s	1100/s	2000/30s
VIP7	1200/s	1200/s	2000/30s
VIP8	1500/s	1500/s	2000/30s
VIP9	2000/s	2000/s	2000/30s
VIP10	2500/s	2500/s	2000/30s
VIP11	3500/s	3500/s	2000/30s
VIP12	4000/s	4000/s	2000/30s

4. 母子帳戶限頻規則

採用「母子帳戶統一限頻 + 額度自主分配」模式

系統將根據使用者的 VIP 等級，為使用者分配統一的 UTA API 總限頻額度；

所有子帳戶共享同一使用者維度的總限頻池，使用者可自主將總限頻額度分配至不同子帳戶；
【相關接口】

UTA REST 取得 API 速率限制

UTA REST 取得所有 API 速率限制

UTA REST 取得 API 速率限制上限

UTA REST 設置子帳戶 API 速率限制

新子帳戶的 API 預設限頻為：10 次／秒。該預設值不計入用戶 API 限頻總配額；

母帳戶限頻額度 = 用戶目前總限頻額度 - 子帳戶已佔用總額（不包含預設值 10 次／秒）。

升降級規則

升級規則
若發生升級，母子帳戶限頻上限將同步提升，使用者可手動重新設定子帳戶限頻。

降級規則
若發生降級，子帳戶限頻將依比例自動調整為新的限頻值，並根據子帳戶限頻總值更新母帳戶限頻。
示例：
使用者由 VIP7 降級至 VIP5
總限頻額度由 1000 調整至 700
每個 UID 的限頻值將依照 70% 比例同步下調。

5. 額外限制&申請更高限制

5.1 伺服器超載限制

除常規速率限制外，伺服器超載可能觸發臨時速率限制。此時，系統將返回錯誤代碼 429000，但回應標頭不包含個人速率限制資訊。此類限制不計入常規速率限制配額。建議稍後重試。

5.2 申請更高限制

若您為專業交易者或做市商，需要更高的速率限制配額，請將以下資訊發送至 api@kucoin.com：

KuCoin 帳戶資訊

申請原因

預估交易量

WebSocket 限頻規則

1. 最大並發連線數

每個 IP：公有 ≤ 1024 + 私有 ≤ 1024（總計 2048）
按 IP 統計；公有與私有連線分開計算

2. 建立連線速率

每個 IP 每 5 分鐘最多建立 300 個新連線
此限制適用於所有新建 WebSocket 連線，包括用於訂閱、下單、撤單等場景的連線。若短時間內超限，伺服器可能拒絕新的連線請求。
建議重複使用既有連線，避免頻繁斷開與重連。

3. 客戶端到服務端訊息（Client → Server）

限制：每 10 秒 100 條訊息
統計範圍：以單一連線計算；包含 subscribe、unsubscribe、ping。
透過 WebSocket 發送的下單和撤單訊息不計入此限制，而是和REST下撤單共享限頻。
若超限，伺服器可能斷開該 WebSocket 連線。

4. 單一連線最大訂閱 Topics 數

限制：≤ 200 個 topics

5. 使用建議

盡可能重複使用既有 WebSocket 連線。

控制客戶端訊息發送頻率（每個連線每 10 秒不超過 100 條）。

當需訂閱大量 topics 時，請分散到多個連線中處理。

其他說明

1. WebSocket 連線控制

對於發起新的 UTA WebSocket 市場推送連線，還有一條基於滑動視窗的限頻校驗規則：每個 IP 在 5 分鐘內最多 300 次。因為近期閘道曾遭受 DDoS 攻擊，導致服務中斷，所以使用者側也需要實現連線頻率控制。當您在收到 WebSocket 斷開連線後（無論是因為 429 或是其他錯誤），請在重連前增加一個 sleep（例如 3 秒或 5 秒），這樣這個問題應當可以自動恢復。

例如，當您在 10:03 從某個 IP 發起連線時，我們會檢查該 IP 在此前 5 分鐘的滑動視窗內（即 09:58 到 10:03）發起的連線總數是否超過 300。當系統在 10:07 再次檢查時，這個視窗就會滑動為 10:02 到 10:07。

2. 负载均衡机制

系統將根據各實例的即時負載情況，動態進行流量均衡與資源調配，幫助客戶獲得更穩定的連接品質與更優的延遲體驗。此機制會作用於UTA下撤單和WS推送
後續在進行負載切換時，部分 WebSocket 連接可能出現服務器主動斷開的情況。此類負載切換預計每週最多發生一至兩次，重新建立連接後即可恢復正常。

3. V1 和 V2 的限频兼容

V1 與 V2 API 的請求將共同消耗對應限頻池的限頻額度；

升級至 V2 不會產生獨立於 V1 之外的額外限頻配額；

速率限制規則（UTA）

UTA RESTful 速率限制#

1.資源池介紹#

1.1 私有限頻池（Private Rate Limit Pool）#

1.2 公有限頻池（Public Rate Limit Pool）#

2. 權重#

2.1 權重規則介紹#

2.2 HTTP Header 查詢#

3. VIP 等級限頻額度分配#

4. 母子帳戶限頻規則#

5. 額外限制&申請更高限制#

5.1 伺服器超載限制#

5.2 申請更高限制#

WebSocket 限頻規則#

1. 最大並發連線數#

2. 建立連線速率#

3. 客戶端到服務端訊息（Client → Server）#

4. 單一連線最大訂閱 Topics 數#

5. 使用建議#

其他說明#

1. WebSocket 連線控制#

2. 负载均衡机制#

3. V1 和 V2 的限频兼容#