제한 및 보안

오류 및 요청 제한

공개 프로필 API에서 지원하는 region은 tw, jp, en, kr이며, ID는 정밀도 손실 방지를 위해 10진수 문자열로 전달해야 합니다. 모든 요청은 Authorization: Bearer <Secret> 헤더를 포함해야 하며 별도의 clientID 헤더는 요구되지 않습니다. 저장 데이터 다운로드 시에는 saveServer(intl 또는 jp)와 accountID(업로드된 파일 최상위의 _profileId)를 지정해야 하며, saves:read 권한 및 해당 저장 데이터에 대한 사용자의 명시적인 승인이 필수적입니다. 공개 API의 기본 호출 한도는 Passport 사용자 계정 단위로 모든 앱과 API 키에 걸쳐 분당 100회, 일일 10000회로 제한됩니다. 동시 요청 제한은 사용자당 4개, 플랫폼 전체 32개입니다(실제 배포 구성에 따라 세부 수치는 조정될 수 있습니다). 503은 서비스 일시 점검 또는 상위 서비스 장애를 나타냅니다. 오류 응답 구조의 경우 게임 API는 {error:{kind}} 형식을, 저장 데이터 및 플랫폼 관리 API는 {error:string} 형식을 반환합니다.

호출 한도는 고정된 UTC 1분 단위 창(Window) 및 UTC 일자 단위 할당량을 기준으로 계산되며, 동일한 Passport 사용자 계정 내의 모든 앱, API 키, 리전 간에 공유됩니다. 새 앱을 생성하거나 API 키를 교체하더라도 사용량 카운터는 초기화되지 않습니다. 인증, 권한 확인, 요청 구문 검증을 통과한 유효 요청만 한도에서 차감되며, 여기에는 캐시 적중 및 업스트림 오류 응답도 포함됩니다. 인증 실패, 권한 부족(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 인증 API와는 독립적으로 운영되는 서비스입니다. 요청 시 인증 헤더를 포함하지 않는 일반 GET 요청을 사용해야 하며, clientSecret을 전송해서는 안 됩니다. 해당 엔드포인트에는 Passport의 '분당 100회 / 일일 10,000회' 호출 제한이 적용되지 않지만, 전용 할당량 보장, 고정된 갱신 주기, 외부 브라우저 환경에서의 무제한 CORS 접근을 보장하는 것은 아닙니다. 적절한 캐싱 정책과 호출 빈도를 준수해 주세요.