에러 코드
무엇이 막혔고 어떻게 뚫는지 — 에러 코드 안내서
에러 코드는 막다른 길이 아니라 다음에 뭘 하면 되는지 알려주는 표지판입니다. 아래 표에서 코드를 찾아 "이렇게 하세요"만 따라가면 대부분 몇 분 안에 풀립니다.
용어 한 가지 — 플랜
이 문서에서 플랜은 구독 등급인 Basic · Standard · Pro를 가리킵니다. 라이선스 검증 API 응답에서는 이 값이 tier 필드에 담겨 옵니다("basic" · "standard" · "pro") — 즉 tier 필드 = 지금 사용 중인 플랜입니다.
라이선스 에러
앱을 켤 때 라이선스 검증에서 나오는 코드입니다. 앱이 실행되지 않는다면 대개 여기서 시작하세요.
| 코드 | HTTP | 무슨 뜻인가요 | 이렇게 하세요 |
|---|---|---|---|
LICENSE_NOT_FOUND | 404 | 라이선스 키를 찾지 못했습니다 | assets/license.key 파일이 있는지 확인하세요 |
LICENSE_EXPIRED | 403 | 라이선스 기간이 만료됐습니다 | 구독을 갱신하면 바로 풀립니다 |
LICENSE_INACTIVE | 403 | 아직 활성화되지 않았습니다 | 마이페이지에서 활성화하세요 |
PACKAGE_MISMATCH | 403 | 패키지명이 등록 값과 다릅니다 | 앱 설정의 패키지명을 다시 맞추세요 |
SIGNATURE_MISMATCH | 403 | 서명 해시가 등록 값과 다릅니다 | 서명 해시를 다시 등록하세요 |
INVALID_SIGNATURE | 401 | HMAC 검증에 실패했습니다 | 라이선스 키 파일을 재발급받으세요 |
인증 에러
대시보드/계정 관련 요청에서 나오는 코드입니다.
| 코드 | HTTP | 무슨 뜻인가요 |
|---|---|---|
UNAUTHORIZED | 401 | 로그인 토큰이 없거나 만료됐습니다 — 다시 로그인하세요 |
FORBIDDEN | 403 | 이 작업을 할 권한이 없습니다 |
Bridge 에러
앱 안의 JavaScript에서 window.unveilyBridge를 호출할 때, 결과 콜백으로 돌아오는 값입니다.
모양이 조금씩 달라요
브릿지마다 결과 형태가 조금씩 다릅니다. 취소는 보통 { cancelled: true }로, 실패는 { error: "..." } 또는 { success: false, error: "..." }로 옵니다. 각 브릿지 문서의 "콜백" 절에 정확한 형태가 정리돼 있습니다.
| 코드 | 무슨 뜻인가요 |
|---|---|
CANCELLED | 사용자가 직접 취소했습니다 (예: 스캐너를 닫음) |
PERMISSION_DENIED | 시스템 권한이 없습니다 — 매니페스트 권한 주석 해제 / iOS Info.plist 사용 설명 키를 확인하세요 |
FEATURE_NOT_ALLOWED | 지금 플랜에 포함되지 않은 기능입니다 — 상위 플랜에서 열립니다 |
SDK_NOT_READY | iOS에서 아직 준비되지 않은 기능입니다 (예: Kakao/Naver/Line/Meta 로그인은 향후 iOS SDK 업데이트 예정) |
NOT_SUPPORTED | 현재 플랜에서 지원하지 않는 기능입니다 |
UNAVAILABLE | 이 기기 자체가 지원하지 않는 기능입니다 (하드웨어 없음 등) |
TIMEOUT | 응답이 제한 시간을 넘겼습니다 — 다시 시도하세요 |
플랜에 막혔을 때
기능을 부르기 전에 지금 플랜에서 쓸 수 있는지 먼저 확인하면 위 에러를 피할 수 있습니다. 현재 플랜은 unveilyBridge.app.getInfo()의 tier 값으로, 모듈 활성 여부는 unveilyBridge.modules.isEnabled("...")로 확인하세요.