이 페이지에는 일반적인 오류 코드와 오류 코드가 나타내는 내용, 앱이나 게임에서 이에 대응할 수 있는 방식이 나열되어 있습니다.
| 오류 코드 | 설명 | 조치 |
|---|---|---|
API_NOT_AVAILABLE |
Integrity API를 사용할 수 없습니다. Integrity API가 사용 설정되지 않았거나 Play 스토어 버전이 오래되었을 수 있습니다. | 1) Google Play Console에서 Play Integrity API가 사용 설정되어 있는지 확인합니다. 2) 사용자에게 Google Play 스토어를 업데이트해 달라고 요청합니다. |
NETWORK_ERROR |
사용 가능한 네트워크를 찾을 수 없습니다. | 사용자에게 네트워크 연결을 확인해 달라고 요청합니다. |
PLAY_STORE_NOT_FOUND |
기기에서 공식 Play 스토어 앱을 찾을 수 없습니다. | 사용자에게 Google Play 스토어를 설치하거나 사용 설정해 달라고 요청합니다. |
PLAY_STORE_VERSION_OUTDATED |
Play 스토어 앱을 업데이트해야 합니다. | 사용자에게 Google Play 스토어를 업데이트해 달라고 요청합니다. |
PLAY_STORE_ACCOUNT_NOT_FOUND |
기기에서 Play 스토어 계정을 찾을 수 없습니다. Play Integrity API가 이제 인증되지 않은 요청을 지원합니다. 이 오류 코드는 지원되지 않는 이전 Play 스토어 버전에만 사용됩니다. | 사용자에게 Google Play 스토어에 로그인해 달라고 요청합니다. |
CANNOT_BIND_TO_SERVICE |
Play 스토어의 서비스에 바인딩할 수 없습니다. 기기에 이전 Play 스토어 버전이 설치되어 있기 때문일 수 있습니다. | 사용자에게 Google Play 스토어를 업데이트해 달라고 요청합니다. |
APP_NOT_INSTALLED |
호출 앱이 설치되어 있지 않습니다. | 문제가 발생했습니다. 공격일 수 있습니다. 작업이 불가능합니다. |
PLAY_SERVICES_NOT_FOUND |
Play 서비스를 사용할 수 없거나 업데이트해야 합니다. | 사용자에게 Play 서비스를 설치하거나 사용 설정해 달라고 요청합니다. |
PLAY_SERVICES_VERSION_OUTDATED |
Play 서비스를 업데이트해야 합니다. | 사용자에게 Google Play 서비스를 업데이트해 달라고 요청합니다. |
TOO_MANY_REQUESTS |
호출 앱이 API에 너무 많은 요청을 해 제한되었습니다. |
|
REQUEST_HASH_TOO_LONG |
제공된 requestHash가 너무 깁니다. requestHash 길이는 500자(영문 기준) 미만이어야 합니다. |
더 짧은 requestHash로 다시 시도하세요. |
GOOGLE_SERVER_UNAVAILABLE |
알 수 없는 내부 Google 서버 오류입니다. | 지수 백오프로 다시 시도합니다. |
CLIENT_TRANSIENT_ERROR |
클라이언트 기기에 일시적인 오류가 발생했습니다. 표준 API 요청의 경우 Kotlin 및 Java 프로그래밍 언어용 라이브러리 버전 1.3.0, Unity용 Google Play Integrity 플러그인 1.3.0 이상, Play Core Native SDK 1.13.0 이상부터 지원됩니다. | |
INTERNAL_ERROR |
알 수 없는 내부 오류입니다. | 지수 백오프로 다시 시도합니다. |
NONCE_TOO_SHORT |
nonce 길이가 너무 짧습니다. nonce는 최소 16바이트(base64 인코딩 전)여야 합니다. | 더 긴 nonce로 다시 시도합니다. |
NONCE_TOO_LONG |
nonce 길이가 너무 깁니다. nonce는 base64 인코딩 전에 500바이트 미만이어야 합니다. | 더 짧은 nonce로 다시 시도합니다. |
NONCE_IS_NOT_BASE64 |
nonce 형식이 base64, 웹 안전, 줄바꿈 없음이 아닙니다. | 정확한 nonce 형식으로 다시 시도합니다. |
CLOUD_PROJECT_NUMBER_IS_INVALID |
입력한 클라우드 프로젝트 번호가 잘못되었습니다. | Play Integrity API를 사용 설정한 Cloud 프로젝트의 Cloud 프로젝트 번호를 사용합니다. |
APP_UID_MISMATCH |
호출 앱 UID(사용자 ID)가 패키지 관리자의 UID와 일치하지 않습니다. | 문제가 발생했습니다. 공격일 수 있습니다. 작업이 불가능합니다. |
INTEGRITY_TOKEN_PROVIDER_INVALID |
StandardIntegrityTokenProvider가 잘못되었습니다. 이 오류 코드는 Kotlin 및 Java 프로그래밍 언어용 라이브러리 버전 1.3.0, Unity용 Google Play Integrity 플러그인 1.3.0 이상, Play Core Native SDK 1.13.0 이상부터 지원되는 표준 API 요청에만 사용할 수 있습니다. |
새 무결성 토큰 제공자를 요청합니다. |
네이티브 관련 오류 코드
INTEGRITY_ 접두사는 네이티브 오류 코드 앞에 추가되어 잠재적인 이름 지정 충돌을 방지합니다. 위에 나열된 오류 코드 외에 네이티브 API에는 다음 오류 코드도 포함됩니다.
| 오류 코드 | 설명 | 조치 |
|---|---|---|
INTEGRITY_INITIALIZATION_NEEDED |
IntegrityManager가 초기화되지 않았습니다. | IntegrityManager_init()를 먼저 호출합니다. |
INTEGRITY_INITIALIZATION_FAILED |
Integrity API를 초기화하는 중에 오류가 발생했습니다. | 지수 백오프로 다시 시도합니다. 버그 신고를 고려해보세요. |
INTEGRITY_INVALID_ARGUMENT |
잘못된 인수가 Integrity API에 전달되었습니다. | 정확한 인수로 다시 시도합니다. |
오류 시 재시도 로직
특정 오류 코드가 발생하면 앱에서 API 호출을 다시 시도해야 합니다. 모든 오류 코드를 검토하고 필요한 경우 애플리케이션이 지수 백오프로 다시 시도하는지 확인합니다. 권장하는 재시도 전략은 다음과 같습니다.
- 첫 번째 실패 후, 재시도하기 전에 5초의 초기 지연 시간을 갖습니다.
- 재시도 횟수는 총 3회이며, 매번 지연 시간이 기하급수적으로 증가합니다(10초, 20초).
재시도를 실행하는 동안 네트워크 연결을 확인하고 기기에 과부하가 일어나지 않도록 합니다.
3회 시도 후에도 계속 오류가 발생하면 클라이언트에서 모든 무결성 검사를 통과하지 못한 것처럼 결과를 처리합니다. 이 오류는 과부하된 기기, 네트워크 연결 문제, 공격자의 시도 등을 포함하되 이에 국한되지 않는 여러 이유로 발생할 수 있습니다.