화면 모드
오류 코드
오류 응답은 { "ok": false, "error": { "code", "message", "details"? }, "trace_id" } 형식이에요. code로 판단하세요.
공통
| HTTP | code | 뜻 |
|---|---|---|
| 400 | INVALID_PARAM | 요청 형식이 잘못됨 (message에 어느 필드인지) |
| 404 | NOT_FOUND | 없는 리소스·경로 |
| 405 | METHOD_NOT_ALLOWED | HTTP 메서드가 틀림 |
| 500 | INTERNAL | 서버 내부 오류 — trace_id와 함께 문의 |
인증
| HTTP | code | 뜻 | 대응 |
|---|---|---|---|
| 401 | MISSING_SIGNATURE | 서명 헤더 없음 | X-App-Key·X-Timestamp·X-Nonce·X-Signature (웹은 Origin) |
| 401 | INVALID_APP_KEY | 모르는 App Key | 키 확인 |
| 401 | INVALID_SIGNATURE | 서명 불일치 | Secret·서명 문자열 확인 — 테스트하기 |
| 401 | TIMESTAMP_SKEW | 기기 시각이 ±300초 넘게 차이 | 응답 server_time으로 보정 후 재시도 |
| 401 | REPLAYED_REQUEST | 이미 쓴 Nonce | 요청마다 새 Nonce |
| 401 | AUTH_REQUIRED | 유저 토큰 없음 | 로그인 후 호출 |
| 401 | AUTH_TOKEN_INVALID | Access Token 만료·잘못됨 | 토큰 갱신 후 재시도 |
| 401 | REFRESH_TOKEN_EXPIRED · _INVALID · _REVOKED | Refresh Token 사용 불가 | 다시 로그인 |
| 401 | REFRESH_TOKEN_REUSED | 이미 쓴 Refresh Token — 모든 세션 종료 | 다시 로그인, 새 토큰 저장 확인 |
| 401 | INVALID_PROVIDER_TOKEN | Google·Apple·플랫폼 토큰 검증 실패 | 토큰 만료·클라이언트 ID 등록 확인 |
| 403 | GAME_SUSPENDED | 게임이 정지 상태 | 운영 담당자 문의 |
| 403 | PLAYER_BANNED | 제재된 유저 | 제재 안내 화면 |
| 403 | PLAYER_DELETED | 파기된 유저 | 새로 시작 안내 |
| 403 | WEB_NOT_ENABLED | 웹 접속이 꺼짐 | 허용 도메인 등록 요청 |
| 403 | ORIGIN_NOT_ALLOWED | 허용 도메인이 아닌 주소 | 게임 주소 등록 요청 |
| 403 | WEB_NOT_SUPPORTED | 웹에서 쓸 수 없는 API | 앱 전용 (스토어 결제·MAX 광고) |
기능
| HTTP | code | 뜻 | 대응 |
|---|---|---|---|
| 400 | PROVIDER_NOT_CONFIGURED | 해당 로그인·결제 연동이 설정되지 않음 | 운영 담당자에게 연동 요청 |
| 409 | VERSION_CONFLICT | 저장 version 불일치 | 다시 읽어 합친 뒤 저장 |
| 409 | ALREADY_LINKED | 다른 유저에 연결된 계정 | 그 계정으로 로그인 |
| 409 | PROVIDER_ALREADY_LINKED | 같은 종류 계정이 이미 연결됨 | — |
| 409 | PURCHASE_OWNED_BY_OTHER | 다른 유저가 등록한 영수증 | 지급하지 않음 |
| 409 | AD_NOT_REWARDED | 보상 확정 전 광고 세션 | 상태 확인 후 다시 |
| 413 | VALUE_TOO_LARGE | 저장 값 크기 초과 | 값 나누기 |
| 422 | RECEIPT_INVALID | 위조·취소·상품 불일치 영수증 | 지급하지 않음 |
| 422 | RECEIPT_REVOKED | 환불·취소된 결제 | 지급하지 않음 |
| 422 | SCORE_OUT_OF_RANGE | 허용 범위 밖 점수 | — |
| 422 | STORAGE_KEY_LIMIT | 키 개수 초과 | 키 합치기 |
| 429 | RATE_LIMITED | 요청 한도 초과 | Retry-After초 후 재시도 |
| 429 | SUBMIT_TOO_FAST | 점수 제출 간격 제한 | 잠시 후 제출 |
| 429 | AD_DAILY_CAP | 오늘 광고 보상 한도 | 광고 버튼 숨김 |
| 429 | EVENT_QUOTA_EXCEEDED | 오늘 이벤트 한도 초과 | 이벤트 줄이기 |
| 500 | STORE_CONFIG_INVALID | 스토어 연동 설정 오류 | 운영 담당자 문의 |
| 503 | STORE_UNAVAILABLE · UPSTREAM_UNAVAILABLE | 스토어·외부 서버 장애 | 스토어 완료 처리 없이 나중에 재시도 |
SDK 전용 코드
| code | 뜻 |
|---|---|
NETWORK_ERROR | 네트워크 끊김·타임아웃 (웹은 CORS 차단 포함) |
NOT_LOGGED_IN | 로그인 전 호출 |
NOT_SUPPORTED | 설치·설정되지 않은 기능 |
CANCELED | 유저가 결제·로그인 취소 |
STORE_ERROR (Unity) · PLATFORM_ERROR (HTML5) | 스토어·플랫폼 SDK 오류 |