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

文件說明

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

核心定義

1. 限流維度

維度識別	維度名稱	維度說明
USER	使用者維度	以呼叫方的使用者唯一識別（如使用者 ID）進行限流
APP	應用程式維度	以呼叫方的應用程式唯一識別（如 API Key 關聯的應用 ID）進行限流
GLOBAL	全域維度	以開放平台整體服務容量進行限流

2. 時間粒度

時間識別	時間單位	說明
SECOND	秒	以「1 秒」為時間視窗統計呼叫次數
MINUTE	分鐘	以「1 分鐘（60 秒）」為時間視窗統計呼叫次數

具體限流規則

開放平台採用多維度、多時間粒度的組合限流策略，任一維度／時間粒度觸發上限均判定為超限：

限流維度	時間粒度	呼叫次數上限	說明
USER	秒	100 次／秒	單一使用者每秒最多呼叫 API 100 次
USER	分鐘	5000 次／分鐘	單一使用者每分鐘最多呼叫 API 5000 次
APP	秒	20 次／秒	單一應用程式每秒最多呼叫 API 20 次
APP	分鐘	1000 次／分鐘	單一應用程式每分鐘最多呼叫 API 1000 次
GLOBAL	秒	3000 次／秒	開放平台全域每秒最多處理 3000 次 API 呼叫
GLOBAL	分鐘	150000 次／分鐘	開放平台全域每分鐘最多處理 150000 次 API 呼叫

注：限流規則遵循「就低不就高」原則，例如：單一使用者 1 秒內呼叫 101 次，即使分鐘級未到 5000 次上限，仍會觸發限流。

限流觸發處理

1. 回傳狀態碼：觸發限流後，介面會立即回傳狀態碼 60001（INTERFACE_RATE_LIMIT）。
2. 恢復機制：觸發限流後，需等待目前時間視窗結束，呼叫次數計數會重置後可恢復正常呼叫。

注意事項

1. 限流計數以 API 實際接收並處理請求為準，參數錯誤、認證失敗等非業務處理請求仍會計入限流次數。
2. 建議於呼叫端實作限流控制邏輯，依本規則合理拆分請求。
3. 若業務場景需要更高呼叫頻率上限，可聯絡開放平台營運申請調整。
4. 限流規則可能依平台容量動態調整，調整前會以公告通知開發者。