> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/tools/web-sdk/errors.md). # 06. 오류 사유 (reason) ### **오류 전달 방식** 오류의 **분기 기준은 `reason` 문자열**입니다. 오류 객체가 게임에 제공하는 값은 `e.reason`(분기용)과 `e.message`(로그용) 두 가지이며, **숫자 오류 코드는 전달되지 않습니다.**
API 종류오류 전달 형태
Lifecycle · 기타 API (initializeAsync · startGameAsync · openDeeplink)Promise reject. 오류 객체 e.reason(사유) · e.message(로그용 문구)
광고 API (showRewardedAsync · showInterstitialAsync)reject하지 않고 { status: "failed", reason }으로 resolve (04. 인앱 광고 (IAA) 참고)
구매/결제 · 상품 정보 조회 API (iap.purchase · iap.getProductDetailsAsync)성공 시 결과 객체로 resolve, 실패 · 취소는 Promise reject. e.reason · e.message (아래 '구매/결제 · 상품 정보 조회 오류' 참고). 상품 정보 조회의 빈 배열은 실패가 아니라 정상 resolve입니다 (05. 인앱 결제 (IAP) 참고)
최종 사용자에게 노출할 문구는 `reason`을 기준으로 게임에서 결정합니다. `message`는 로그 · 디버깅용 보조 문구이며 분기 조건으로 사용하지 않습니다. ### **공통 오류** | reason | description | | ------------------------ | --------------------------------------------------------------------------------------------------- | | invalid\_params | 필수 파라미터 누락 · 형식 오류 · 값 범위 위반 | | unsupported\_action | 이 앱 버전이 처리할 수 없는 요청 | | platform\_not\_supported | 이 환경 · 앱 버전에서 제공하지 않는 기능. SDK가 앱에 묻지 않고 판정합니다. 일반 브라우저에서 실행한 경우와 앱 버전이 그 기능을 제공하지 않는 경우가 모두 이 사유입니다 | | user\_cancelled | 사용자가 취소. 오류 팝업을 띄우지 말고 원래 흐름으로 복귀하십시오 | | rate\_limited | 호출 빈도 제한 초과. 즉시 재호출하지 마십시오 | | timeout | 액션별 제한 시간 안에 결과가 나오지 않음 | | internal\_error | 그 밖의 내부 처리 실패. 모르는 사유를 받은 경우도 이와 같이 취급하십시오 | ### **광고 전용 오류** | reason | description | | ------------------- | ----------------------------------------------------------------------------------------------------------- | | invalid\_request | 필수 파라미터 누락 · 등록되지 않은 지면 ID · 지면 유형 불일치. `placementId`나 리워드의 `requestId`가 없으면 SDK가 앱에 보내지 않고 즉시 이 사유로 실패시킵니다 | | unsupported\_screen | 광고를 지원하지 않는 화면에서의 호출 | | not\_initialized | 광고 SDK 초기화 미완료 | | no\_fill | 표시할 광고 없음. **보상 지급 대상이 아닙니다.** 광고 없이 진행할 대체 경로를 두십시오 | | show\_failed | 광고 표시 실패 (재생이 시작되지 않고 종료된 경우, 화면이 가려진 상태에서 요청이 도착한 경우 포함) | | timeout | 타임아웃 발생 (오류 발생 이후에 광고가 노출될 가능성 있음). 반환된 `requestId`로 중복 지급을 방어하십시오 | | already\_showing | 광고 재생 중 재호출 · 결제 진행 중 광고 요청 | | network\_error | 통신 계층 실패 | ### **SDK 판정 오류** 아래 오류는 앱 호출 없이 SDK가 스스로 판정합니다. | reason | description | | ------------------------ | ------------------------------------------------------------- | | sdk\_not\_initialized | `initializeAsync()` 완료 전에 순서가 필요한 API(`startGameAsync` 등)를 호출 | | platform\_not\_supported | 이 환경 · 앱 버전이 제공하지 않는 기능을 호출 (예: 광고를 지원하지 않는 앱 버전에서의 광고 요청) | ### **구매/결제 · 상품 정보 조회 오류** *두 API가 같은 오류 사유 체계를 씁니다.* | reason | description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | invalid\_request | 필수 파라미터 누락 · 형식 오류 · `developerPayload` 200바이트 초과 · 상품 정보 조회의 상품 ID 목록이 비었거나 빈 문자열을 포함하거나 20개 초과 · 결제 모듈이 요청을 잘못된 요청으로 판정 | | user\_cancelled | 사용자가 결제를 취소 | | service\_unavailable | 단말 · 서버 네트워크 오류 · 구매 처리 과정 오류 | | already\_owned | 미소비 상태로 이미 보유 중 (소비 전 재구매) | | payment\_failed | 결제 실패. 결제 가능 여부 · 결제 수단 확인 필요 | | need\_login | 스토어 앱 미로그인 | | security\_error | 비정상 앱 결제 요청 · 필수 권한 요청 취소 | | already\_processing | 결제 또는 광고 UI 표시 중의 결제 요청 (전체화면 UI 동시 표시 제한). 상품 정보 조회는 화면을 덮지 않으므로 이 제한을 받지 않습니다 | | need\_update | 원스토어 서비스 앱 미설치 · 구버전. 사용자에게 앱 업데이트 안내가 필요합니다 | | timeout | 상품 정보 조회가 10초 안에 응답하지 않음. 잠시 후 다시 시도하십시오. 결제에는 해당하지 않습니다 | | internal\_error | 그 밖의 내부 처리 실패 | | platform\_not\_supported | 이 환경 · 앱 버전이 구매/결제 · 상품 정보 조회를 제공하지 않음. SDK가 앱에 묻지 않고 판정합니다. 일반 브라우저에서 실행한 경우와 해당 기능을 지원하지 않는 앱 버전이 모두 이 사유입니다. `initializeAsync()` 이후 결제는 `sdk.iap.isSupported()`, 상품 정보 조회는 `sdk.iap.isSupported("getProductDetails")`로 사전 확인하십시오 |