制限とセキュリティ

エラーと制限

公開 profile を呼び出す際、region は tw/jp/en/kr を指定し、ID は10進数の文字列で渡します。リクエストヘッダーには Authorization: Bearer <Secret> を指定し、clientID ヘッダーは不要です。セーブデータ API を利用する場合、saveServer は intl/jp を指定し、accountID はアップロードしたセーブの最上位にある _profileId を指定します（saves:read スコープおよび対象セーブに対するユーザーの明示的な許可が必要です）。公開 API のレート制限は Passport ユーザー単位（名下の全アプリ・キー間で共有）で管理され、既定値は毎分 100 回、毎日 10000 回、同時実行数はユーザーごと 4 件、全体 32 件です（制限値はデプロイ設定により異なる場合があります）。503 はサービスまたは受付ゲートウェイが一時的に利用不可であることを示します。ゲーム API のエラー形式は {error:{kind}}、セーブおよび管理 API は {error:string} です。

利用枠は固定の UTC 分および UTC 暦日を基準として、Passport アカウントごとに全アプリ・キー・リージョン間で共有されます。新規アプリ作成やキーのローテーションを行っても使用枠はリセットされません。キーの有効性、権限、パラメータ構文のチェックを通過した時点で利用枠が消費され、キャッシュヒットや上流エラー時もカウントされます。無効な認証情報（401）、権限不足（403）、入力形式不正（400）などの受付前エラーはカウントされません。ヘッダーの X-RateLimit-* および X-Quota-* で現在の利用状況を確認できます。制限を超過した場合は 429 ステータスコードと待機秒数を示す Retry-After ヘッダーが返されます。ゲーム API の同時実行制限はユーザーあたり 4、プロセス全体で 32 です。セーブダウンロードには別途アプリあたり 2、プロセス全体で 16 の同時実行制限が適用されます。

サーバー専用の Secret・OAuth ではありません

Secret はサーバーのみで保管し、ブラウザーのコード、URL、公開リポジトリには含めないでください。OAuth の認可コード、コールバック、ユーザートークンは発行されません。新しいキーの導入後に古いキーを取り消してください。

本プラットフォームはゲーム運営会社の公式 API ではありません。アプリの作成や API キーの管理（発行・失効）はメインサイトのコンソールで行ってください（本静的ドキュメントサイトは閲覧専用です）。アプリの作成に手動審査は不要です。各アプリで保持できる有効なキーは最大2つまでです。キーのローテーションを行う際は、先にクライアント側を新しいキーへ切り替えて動作確認した上で、古いキーを明示的に失効させてください。

公開イベント・楽曲ランキング

イベント・楽曲・チャレンジランキングのデータ取得には、メインサイトでも利用されている公開サービス https://api.bdon.moe/api/v1 の利用を推奨します。本サービスは Passport 認証システムから独立しており、すべての公開エンドポイントは認証情報なし（clientSecret 不要）の GET リクエストを受け付けます。Passport の毎分 100 回 / 毎日 10000 回の制限も消費しません。なお、公開サービスでは固定の更新間隔やサードパーティ製ブラウザ向けの CORS 対応は保証されておらず、無制限のリクエストを許容するものでもありません。適切な頻度で呼び出し、ローカルキャッシュを活用してください。