---
url: https://developers.webzenk.kr/api/errors.md
---
# 오류 코드

오류 응답은 `{ "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·서명 문자열 확인 — [테스트하기](/guide/testing#서명-확인-rest-직접-호출) |
| 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 오류 |
