REST API v1 · 開發者

速率限制

限制是以每把 API 金鑰、固定一分鐘的時間窗口計算,額度大小取決於伺服器的方案。每個通過驗證的回應都會告訴你目前的使用狀況,所以守規矩的用戶端完全不需要猜測。

開發者文件
本頁目錄

各方案的限制

每把 API 金鑰每分鐘的請求數
方案每分鐘請求數可啟用的金鑰數
Free602
Pro 與 Network60010
White Label60040

每把金鑰都有自己的時間窗口,所以同一個伺服器的兩把金鑰不會共用額度。各方案內容請見價格。

速率限制標頭

每個通過驗證的回應都會帶有目前時間窗口的狀態:

回應標頭
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1791374460
  • X-RateLimit-Limit:這把金鑰每分鐘允許的請求數。
  • X-RateLimit-Remaining:目前時間窗口內剩餘的請求數。
  • X-RateLimit-Reset:時間窗口重置的 Unix 時間(秒)。

超過限制時

超過限制時,你會收到 429 RATE_LIMITED,並帶有 Retry-After 標頭,以及內容中的數字欄位 retryAfter(兩者的單位都是秒)。等待這段時間後再重試。

回應 · 429
HTTP/1.1 429 Too Many Requests
Retry-After: 18

{ "error": "RATE_LIMITED", "message": "Rate limit of 60 requests per minute exceeded", "retryAfter": 18 }
Node.js
// Wait and retry on 429 / 503, using the server's Retry-After
async function call(url, init, tries = 3) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(url, init);
    if ((res.status !== 429 && res.status !== 503) || attempt >= tries) return res;
    const seconds = Number(res.headers.get('Retry-After')) || attempt * 2;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

同一個 IP 位址重複使用無效金鑰發出請求,也會被限流:每分鐘失敗次數超過少數幾次後,就會回傳 429 而不是 401。

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。