앱이 Play Integrity API 요청을 하고 호출이 실패하면 앱에 오류 코드가 수신됩니다. 이러한 오류는 네트워크 연결 불량과 같은 환경 문제, API 통합 문제, 악의적인 활동 및 활성 공격 등 다양한 이유로 발생할 수 있습니다. 반환되는 오류 코드의 유형은 요청 유형에 따라 다릅니다.
- 표준 요청: API가 StandardIntegrityErrorCode를 반환합니다.
- 기존 요청: API가 IntegrityErrorCode를 반환합니다.
재시도 전략
백그라운드에서 이루어지며 사용자가 세션을 진행하는 동안 사용자 경험에 영향을 주지 않는 Play Integrity 작업에는 지수 백오프를 사용합니다.
예를 들어 새 구매를 확인하는 작업은 백그라운드에서 이루어질 수 있고 오류가 발생한 경우에도 확인이 실시간으로 이루어질 필요가 없으므로 지수 백오프를 구현하는 것이 적절합니다.
첫 번째 실패 후, 재시도하기 전에 5초의 초기 지연 시간을 갖습니다.
매번 기하급수적으로 증가하는 지연(10초, 20초)을 사용하여 최대 시도 횟수를 종료 조건으로 사용하는 재시도 전략을 구현합니다.
재시도를 실행하는 동안 네트워크 연결을 확인하고 기기에 과부하가 일어나지 않도록 합니다.
3회 재시도 후에도 계속 오류가 발생하면 클라이언트에서 모든 무결성 검사를 통과하지 못한 것처럼 결과를 처리합니다. 이 오류는 과부하된 기기, 네트워크 연결 문제, 공격자의 시도 등을 포함하되 이에 국한되지 않는 여러 이유로 발생할 수 있습니다.
Java 라이브러리의 오류 코드 값
네이티브 라이브러리의 추가 오류 코드 값
재시도 가능한 오류 코드
이러한 오류의 원인은 일시적인 조건으로 인해 발생할 수 있으므로 호출을 다시 시도해야 합니다.
NETWORK_ERROR(오류 코드 -3)
이 오류는 기기와 Play 시스템 간의 네트워크 연결에 문제가 있음을 나타냅니다.
가능한 해결 방법
복구하려면 사용자에게 네트워크 연결을 확인하도록 요청하고 오류를 트리거한 작업에 따라 간단한 재시도 또는 지수 백오프를 사용합니다.
참고 항목
기존 요청의 경우 NETWORK_ERROR
TOO_MANY_REQUESTS(오류 코드 -8)
호출 앱이 API에 너무 많은 요청을 해 제한되었거나 앱이 일일 요청 할당량을 초과했습니다.
가능한 해결 방법
- 지수 백오프로 다시 시도합니다.
- 일일 최대 요청 수 증가를 요청합니다.
참고 항목
기존 요청의 경우 TOO_MANY_REQUESTS
GOOGLE_SERVER_UNAVAILABLE(오류 코드 -12)
알 수 없는 내부 Google 서버 오류입니다.
가능한 해결 방법
지수 백오프로 다시 시도합니다. 계속 실패하는 경우 버그 신고를 고려해 보세요.
참고 항목
기존 요청의 경우 GOOGLE_SERVER_UNAVAILABLE
CLIENT_TRANSIENT_ERROR(오류 코드 -18)
클라이언트 기기에 일시적인 오류가 발생했습니다.
표준 API 요청의 경우 Kotlin 및 Java용 Play Integrity API 라이브러리 버전 1.3.0, Unity용 Google Play Integrity 플러그인 1.3.0 이상, Play Core Native SDK 1.13.0 이상부터 지원됩니다.
가능한 해결 방법
지수 백오프로 다시 시도합니다.
참고 항목
기존 요청의 경우 CLIENT_TRANSIENT_ERROR
참고: 기존 API 요청을 사용하는 동안 보고되면 반환되는 값은 -17입니다.
INTERNAL_ERROR(오류 코드 -100)
알 수 없는 내부 오류입니다.
가능한 해결 방법
지수 백오프로 다시 시도합니다. 계속 실패하는 경우 버그 신고를 고려해 보세요.
참고 항목
기존 요청의 경우 INTERNAL_ERROR
STANDARD_INTEGRITY_INTERNAL_ERROR(오류 코드 -100)
알 수 없는 내부 오류입니다.
가능한 해결 방법
지수 백오프로 다시 시도합니다. 계속 실패하는 경우 버그 신고를 고려해 보세요.
참고 항목
기존 요청의 경우 INTEGRITY_INTERNAL_ERROR를 참고하세요.
STANDARD_INTEGRITY_INITIALIZATION_FAILED(오류 코드 -102)
Standard Integrity API를 초기화하는 중에 오류가 발생했습니다.
가능한 해결 방법
지수 백오프로 다시 시도합니다. 계속 실패하는 경우 버그 신고를 고려해 보세요.
참고 항목
기존 요청의 경우 INTEGRITY_INITIALIZATION_FAILED를 참고하세요.
재시도할 수 없는 오류 코드
이 경우에는 자동 재시도가 도움이 되지 않습니다. 단, 사용자가 문제의 원인이 된 조건을 해결한다면 수동 재시도가 도움이 될 수 있습니다. 예를 들어 사용자가 Play 스토어 버전을 지원되는 버전으로 업데이트한다면 처음에 시도한 작업을 수동으로 재시도하는 것이 해결 방법이 될 수 있습니다.
API_NOT_AVAILABLE(오류 코드 -1)
기기에 설치된 Play 스토어 버전이 오래되었을 수 있으며 Integrity API를 사용할 수 없습니다. 또는 Integrity API가 Google Play Console에서 사용 설정되어 있지 않을 수 있습니다.
가능한 해결 방법
- Google Play Console에서 Integrity API가 사용 설정되어 있는지 확인합니다.
- 사용자에게 Play 스토어를 업데이트하라고 요청합니다.
참고 항목
기존 요청은 API_NOT_AVAILABLE을 참고하세요.
PLAY_STORE_NOT_FOUND(오류 코드 -2)
기기에서 공식 Play 스토어 앱을 찾을 수 없습니다.
가능한 해결 방법
사용자에게 Google Play 스토어를 설치하거나 사용 설정해 달라고 요청합니다.
참고 항목
기존 요청은 PLAY_STORE_NOT_FOUND를 참고하세요.
PLAY_STORE_ACCOUNT_NOT_FOUND(오류 코드 -4)
참고: 이는 IntegrityErrorCode를 통해 기존 요청에 관해서만 보고됩니다.
기기에서 Play 스토어 계정을 찾을 수 없습니다. Play Integrity API가 이제 인증되지 않은 요청을 지원합니다. 이 오류 코드는 지원되지 않는 이전 Play 스토어 버전에만 사용됩니다.
가능한 해결 방법
사용자에게 Google Play 스토어를 업데이트하고 로그인해 달라고 요청합니다.
APP_NOT_INSTALLED(오류 코드 -5)
호출 앱이 설치되어 있지 않습니다. 문제가 발생했습니다. 공격일 수 있습니다.
가능한 해결 방법
작업이 불가능합니다. 클라이언트가 모든 무결성 검사에 실패한 것처럼 결과를 처리합니다.
참고 항목
기존 요청은 APP_NOT_INSTALLED를 참고하세요.
PLAY_SERVICES_NOT_FOUND(오류 코드 -6)
Play 서비스를 사용할 수 없거나 업데이트해야 합니다.
가능한 해결 방법
사용자에게 Play 서비스를 설치하거나 업데이트하거나 사용 설정해 달라고 요청합니다.
참고 항목
기존 요청은 APP_NOT_INSTALLED를 참고하세요.
APP_UID_MISMATCH(오류 코드 -7)
호출 앱 UID(사용자 ID)가 패키지 관리자의 UID와 일치하지 않습니다.
가능한 해결 방법
작업이 불가능합니다. 클라이언트가 모든 무결성 검사에 실패한 것처럼 결과를 처리합니다.
참고 항목
기존 요청은 APP_UID_MISMATCH를 참고하세요.
CANNOT_BIND_TO_SERVICE(오류 코드 -9)
Play 스토어의 서비스에 바인딩할 수 없습니다. 기기에 이전 Play 스토어 버전이 설치되어 있기 때문일 수 있습니다.
가능한 해결 방법
사용자에게 Google Play 스토어를 업데이트해 달라고 요청합니다.
참고 항목
기존 요청은 CANNOT_BIND_TO_SERVICE를 참고하세요.
NONCE_TOO_SHORT(오류 코드 -10)
참고: 이는 IntegrityErrorCode를 통해 기존 요청에 관해서만 보고됩니다.
nonce 길이가 너무 짧습니다. nonce는 base64 인코딩 전 최소 16바이트여야 합니다.
가능한 해결 방법
더 긴 nonce로 다시 시도합니다.
NONCE_TOO_LONG(오류 코드 -11)
참고: 이는 IntegrityErrorCode를 통해 기존 요청에 관해서만 보고됩니다.
nonce 길이가 너무 깁니다. nonce는 base64 인코딩 전에 500바이트 미만이어야 합니다.
가능한 해결 방법
더 짧은 nonce로 다시 시도합니다.
NONCE_IS_NOT_BASE64(오류 코드 -13)
참고: 이는 IntegrityErrorCode를 통해 기존 요청에 관해서만 보고됩니다.
nonce가 base64, 웹 안전, 줄바꿈 없음 문자열로 인코딩되지 않습니다.
가능한 해결 방법
올바른 형식의 nonce로 다시 시도합니다.
PLAY_STORE_VERSION_OUTDATED(오류 코드 -14)
Google Play 스토어 앱을 업데이트해야 합니다.
가능한 해결 방법
사용자에게 Google Play 스토어를 업데이트해 달라고 요청합니다.
참고 항목
기존 요청은 PLAY_STORE_VERSION_OUTDATED를 참고하세요.
PLAY_SERVICES_VERSION_OUTDATED(오류 코드 -15)
Google Play 서비스를 업데이트해야 합니다.
가능한 해결 방법
사용자에게 Google Play 서비스를 업데이트해 달라고 요청합니다.
참고 항목
기존 요청은 PLAY_SERVICES_VERSION_OUTDATED를 참고하세요.
CLOUD_PROJECT_NUMBER_IS_INVALID(오류 코드 -16)
입력한 클라우드 프로젝트 번호가 잘못되었습니다.
가능한 해결 방법
Play Integrity API를 사용 설정한 Cloud 프로젝트의 Cloud 프로젝트 번호를 사용합니다.
참고 항목
기존 요청은 CLOUD_PROJECT_NUMBER_IS_INVALID를 참고하세요.
REQUEST_HASH_TOO_LONG(오류 코드 -17)
참고: 이는 StandardIntegrityErrorCode를 통해 표준 요청을 사용할 때만 보고됩니다.
제공된 requestHash가 너무 깁니다. requestHash 길이는 500자(영문 기준) 미만이어야 합니다.
가능한 해결 방법
더 짧은 requestHash로 다시 시도하세요.
INTEGRITY_TOKEN_PROVIDER_INVALID(오류 코드 -19)
참고: 이는 StandardIntegrityErrorCode를 통해 표준 요청에 관해서만 보고됩니다.
StandardIntegrityTokenProvider이(가) 더 이상 유효하지 않습니다.
토큰 제공자가 만료되었거나 사용자가 Play 스토어 앱의 데이터를 삭제하여 토큰 제공자가 삭제되었기 때문일 수 있습니다.
이 오류 코드는 Kotlin 및 Java 프로그래밍 언어용 라이브러리 버전 1.3.0, Unity용 Google Play Integrity 플러그인 1.3.0 이상, Play Core Native SDK 1.13.0 이상부터 지원되는 표준 API 요청에만 사용할 수 있습니다.
가능한 해결 방법
새 무결성 토큰 제공자를 요청합니다.
STANDARD_INTEGRITY_INITIALIZATION_NEEDED(오류 코드 -101)
StandardIntegrityManager가 초기화되지 않았습니다.
가능한 해결 방법
먼저 StandardIntegrityManager_init()를 호출합니다.
참고 항목
기존 요청은 INTEGRITY_INITIALIZATION_NEEDED를 참고하세요.
STANDARD_INTEGRITY_INVALID_ARGUMENT(오류 코드 -103)
잘못된 인수가 Standard Integrity API에 전달되었습니다.
가능한 해결 방법
올바른 인수로 다시 시도합니다.
참고 항목
기존 요청은 INTEGRITY_INVALID_ARGUMENT를 참고하세요.