開放平台API請求速率限制說明文件

文件說明

本文件定義了開放平台API的請求速率限制（限流）規則，明確不同維度、不同時間粒度下的API呼叫頻次上限，協助開發者合理控制呼叫頻率，避免触發限流機制導致介面呼叫失敗。

核心定義

1. 限流維度

維度識別	維度名稱	維度說明
USER	使用者維度	基於呼叫方的使用者唯一識別（如使用者ID）進行限流，限制單個使用者的API呼叫頻次
APP	應用維度	基於呼叫方的應用唯一識別（如API Key關聯的應用ID）進行限流，限制單個應用的API呼叫頻次
GLOBAL	全局維度	基於開放平台整體服務容量進行限流，限制全平台所有呼叫方的總API呼叫頻次

2. 時間粒度

時間識別	時間單位	說明
SECOND	秒	以“1秒”為時間窗口統計呼叫頻次
MINUTE	分鐘	以“1分鐘（60秒）”為時間窗口統計呼叫頻次

具体限流規則

開放平台采用多維度、多時間粒度的組合限流策略，任一維度/時間粒度触發上限均會判定為超限，具体規則如下：

限流維度	時間粒度	呼叫頻次上限	說明
USER	秒	100次/秒	單個使用者每秒最多可呼叫API 100次
USER	分鐘	5000次/分鐘	單個使用者每分鐘最多可呼叫API 5000次
APP	秒	20次/秒	單個應用每秒最多可呼叫API 20次
APP	分鐘	1000次/分鐘	單個應用每分鐘最多可呼叫API 1000次
GLOBAL	秒	3000次/秒	開放平台全局每秒最多處理API呼叫3000次
GLOBAL	分鐘	150000次/分鐘	開放平台全局每分鐘最多處理API呼叫150000次

注：限流規則遵循“就低不就高”原則，例如：單個使用者1秒內呼叫101次，即使分鐘級未到5000次上限，也會触發限流；單個應用1分鐘內呼叫1001次，即使秒級未到20次上限，也會触發限流。

限流触發處理

1. 回傳狀態碼：呼叫頻次触發限流後，介面會立即回傳狀態碼 60001（INTERFACE_RATE_LIMIT），具体資訊如下：
   • 狀態碼：60001
   • 提示資訊：Rate limit exceeded, please try again later（介面呼叫頻率超限，請稍後重試）
   • 中文說明：介面呼叫頻率超限，請稍後重試
2. 恢複機制：触發限流後，需等待當前時間窗口結束（如秒級限流需等待1秒，分鐘級限流需等待剩餘分鐘時長），呼叫頻次計數會重置，可恢複正常呼叫。

注意事項

1. 限流計數以API實際接收並處理請求為準，請求參數錯誤、驗證失敗等非業務處理請求仍會計入限流次數；
2. 建議開發者在呼叫端實現限流控制逻輯，依本規則合理拆分請求（如批量請求拆分為多次小額請求），避免集中呼叫触發限流；
3. 若業務情境需要更高的呼叫頻次上限，可聯絡開放平台運营人員申請調整限流阈值；
4. 限流規則可能依平台服務容量動態調整，調整前會提前透過開放平台公告告知開發者。