限流与安全

错误与限流

调用公开游戏接口时，请求的 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）支持，亦非无限制调用接口，请合理规划请求频率并做好本地缓存。