限流與安全

錯誤與限流

呼叫公開遊戲介面時，請求的 region 參數支援 tw/jp/en/kr，ID 一律採用十進位字串。請求標頭需攜帶 Authorization: Bearer <Secret>，無需傳入 clientID 標頭。若呼叫存檔介面，saveServer 支援 intl/jp，accountID 為所上傳存檔頂層的 _profileId，且必須擁有 saves:read 權限及使用者對該指定存檔的明確授權。公開 API 預設依 Passport 使用者維度（跨所有應用程式與金鑰共用）限制呼叫頻率：每分鐘最多 100 次、每日最多 10000 次，並行上限為單一使用者 4、全域 32（實際設定可根據部署進行調整）。遇到 503 狀態碼表示服務或准入閘道目前無法使用。遊戲介面的錯誤回傳格式為 {error:{kind}}，存檔與管理介面回傳格式為 {error:string}。

配額依 Passport 帳號跨應用程式、金鑰與 region 統一共用，採用固定的 UTC 分鐘與 UTC 自然日週期進行統計；建立新應用程式或輪替金鑰不會重設當前配額。請求在通過金鑰有效性、權限驗證及語法檢查准入後即計入配額，快取命中與上游介面故障同樣計費；無效憑證（401）、無權限（403）及參數錯誤（400）等未准入請求不扣除配額。回應標頭 X-RateLimit-* 與 X-Quota-* 提供當前剩餘配額與重設資訊；觸發限流時回傳 429 狀態碼，並附帶 Retry-After 標頭提示退避等待秒數。遊戲查詢並行上限為單一使用者 4、單程序全域 32；存檔下載介面另設單一應用程式並行 2、單程序全域 16 的限制。

伺服器端保存金鑰，不使用 OAuth

Secret 只保存在伺服器端，不得放入瀏覽器程式碼、URL 或公開儲存庫。這不是 OAuth 流程，不發放授權碼、回呼或使用者存取權杖。輪替時先部署新金鑰，再撤銷舊金鑰。

本平台非遊戲官方 API。應用程式建立、金鑰簽發與撤銷等管理操作請統一至主站控制台進行（本靜態文件站僅供查閱）。建立應用程式無需人工審核；每個應用程式最多支援同時保留兩把有效金鑰，輪替金鑰時請先將呼叫端切換至新金鑰，確認生效後再明確撤銷舊金鑰。

公開榜線與歌曲榜

若需查詢榜線、歌曲榜與挑戰榜資料，建議優先使用主站同款公開服務介面 https://api.bdon.moe/api/v1。該服務獨立於 Passport 驗證體系，所有公開端點均支援免驗證直接發送 GET 請求，無需攜帶 clientSecret，且不佔用 Passport 的每分鐘 100 次 / 每日 10000 次配額。請注意：公開服務不保證固定更新週期或任意第三方瀏覽器跨域（CORS）支援，亦非無限制呼叫介面，請合理規劃請求頻率並做好本地快取。