fix(virustotal): tell the user when the key is rejected or the quota is spent

Every non-2xx response collapsed into ERROR, so a 429 read as "HTTP 429: Too
Many Requests" and a mistyped key read as "HTTP 401: Unauthorized" — neither
tells anyone what to do. Both are the common failures: the free tier allows 4
requests a minute, which a batch install trips immediately, and a key with one
wrong character is indistinguishable from a broken service.

Adds INVALID_API_KEY and RATE_LIMITED, mapped in one place and surfaced in both
the sheet and the dialog. A rejected key now gets the same Add key / Get key
actions a missing one already had, and the rate-limit line quotes Retry-After
when VT sends it as a delay in seconds.

The upload path returns Result<String> and cannot carry a status, so it throws
a typed VtHttpException instead — which also stops the retry loop from spending
two more requests against a quota that is already exhausted.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: nqmgaming

app/src/main/java/app/pwhs/universalinstaller/data/remote/VirusTotalService.kt

@@ -61,10 +61,7 @@ class VirusTotalService(
             when (response.status.value) {
                 200 -> parseFileStats(response.bodyAsText())
                 404 -> VtResult(status = VtStatus.NOT_FOUND)
-                else -> VtResult(
-                    status = VtStatus.ERROR,
-                    errorMessage = "HTTP ${response.status.value}: ${response.status.description}",
-                )
+                else -> httpFailure(response)
             }
         }.getOrElse { e ->
             Timber.e(e, "VirusTotal hash lookup failed")
@@ -108,7 +105,7 @@ class VirusTotalService(
             }
         }
         if (response.status.value !in 200..299) {
-            error("upload_url HTTP ${response.status.value}: ${response.status.description}")
+            throwTyped(response, "upload_url")
         }
         return JSONObject(response.bodyAsText()).getString("data")
     }
@@ -167,11 +164,14 @@ class VirusTotalService(
                     }
                 }
                 if (response.status.value !in 200..299) {
-                    error("Upload HTTP ${response.status.value}: ${response.status.description}")
+                    throwTyped(response, "Upload")
                 }
                 return JSONObject(response.bodyAsText()).getJSONObject("data").getString("id")
             } catch (e: java.io.IOException) {
                 // Transient I/O error (EOFException, SocketException, etc.) — retry
+                // A rejected key or an exhausted quota will not fix itself on retry, and each
+                // attempt costs another request against the same quota.
+                if (e is VtHttpException) throw e
                 Timber.w(e, "Upload I/O error on attempt ${attempt + 1}")
                 lastException = e
             }
@@ -211,11 +211,10 @@ class VirusTotalService(
                     }
                 }
                 if (response.status.value !in 200..299) {
-                    return@runCatching VtResult(
-                        status = VtStatus.ERROR,
-                        errorMessage = "Poll HTTP ${response.status.value}",
-                        analysisId = analysisId,
-                    )
+                    // Polling burns a request each time, so this is where the free tier's
+                    // 4/minute is most likely to bite; report it as such rather than as a
+                    // nameless poll failure.
+                    return@runCatching httpFailure(response).copy(analysisId = analysisId)
                 }
                 parseAnalysisResponse(response.bodyAsText(), analysisId)
             }.getOrElse { e ->
@@ -322,6 +321,45 @@ class VirusTotalService(
         )
     }
 
+    /**
+     * Throw a [VtHttpException] carrying the mapped status. Retrying an upload after a 401 or a
+     * 429 only burns the remaining quota, so these must be distinguishable from an I/O failure.
+     */
+    private fun throwTyped(response: HttpResponse, what: String): Nothing {
+        val mapped = httpFailure(response)
+        throw VtHttpException(
+            vtStatus = mapped.status,
+            message = "$what HTTP ${response.status.value}: ${response.status.description}",
+        )
+    }
+
+    /** Carries an actionable [VtStatus] out of the upload path, which returns Result<String>. */
+    class VtHttpException(val vtStatus: VtStatus, message: String) : java.io.IOException(message)
+
+    /**
+     * Map an unsuccessful response to a status the UI can act on.
+     *
+     * 401/403 and 429 used to fall into the generic ERROR branch and surface as
+     * "HTTP 429: Too Many Requests", which tells the user nothing they can do. Both are common:
+     * the free tier allows only 4 requests a minute, which a batch install trips immediately, and
+     * a key with one wrong character looks identical to a broken service.
+     */
+    private fun httpFailure(response: HttpResponse): VtResult = when (response.status.value) {
+        401, 403 -> VtResult(status = VtStatus.INVALID_API_KEY)
+        429 -> VtResult(
+            status = VtStatus.RATE_LIMITED,
+            // Retry-After is optional and may be an HTTP date rather than a delay in seconds.
+            // The UI phrases it as "in N seconds", so pass it on only when it really is N.
+            errorMessage = response.headers["Retry-After"]
+                ?.takeIf { it.isNotBlank() && it.all(Char::isDigit) }
+                .orEmpty(),
+        )
+        else -> VtResult(
+            status = VtStatus.ERROR,
+            errorMessage = "HTTP ${response.status.value}: ${response.status.description}",
+        )
+    }
+
     companion object {
         const val BASE_URL = "https://www.virustotal.com/api/v3"
         private const val HEADER_KEY = "x-apikey"

app/src/main/java/app/pwhs/universalinstaller/domain/model/VtResult.kt

@@ -6,6 +6,10 @@ enum class VtStatus {
     SUSPICIOUS,
     NOT_FOUND,
     NO_API_KEY,
+    /** HTTP 401/403 — the key is wrong, revoked, or lacks access. Distinct from a missing key. */
+    INVALID_API_KEY,
+    /** HTTP 429 — free tier allows 4 requests/minute and 500/day. Retrying later works. */
+    RATE_LIMITED,
     ERROR,
     TOO_LARGE,
     SCANNING,    // hashing + hash lookup

app/src/main/java/app/pwhs/universalinstaller/presentation/install/ApkInfoContent.kt

@@ -605,7 +605,8 @@ private fun VirusTotalCard(
     val vtColor = when (status) {
         VtStatus.CLEAN -> MaterialTheme.colorScheme.primary
         VtStatus.MALICIOUS, VtStatus.ERROR -> MaterialTheme.colorScheme.error
-        VtStatus.SUSPICIOUS, VtStatus.NO_API_KEY, VtStatus.TOO_LARGE -> extendedColors.warning
+        VtStatus.SUSPICIOUS, VtStatus.NO_API_KEY, VtStatus.INVALID_API_KEY,
+        VtStatus.RATE_LIMITED, VtStatus.TOO_LARGE -> extendedColors.warning
         else -> MaterialTheme.colorScheme.onSurfaceVariant
     }
     // Status line — without this, NO_API_KEY / ERROR / TOO_LARGE left the card silent
@@ -616,6 +617,11 @@ private fun VirusTotalCard(
         VtStatus.SUSPICIOUS -> stringResource(R.string.apk_info_vt_suspicious, vt.suspicious)
         VtStatus.NOT_FOUND -> stringResource(R.string.apk_info_vt_not_found)
         VtStatus.NO_API_KEY -> stringResource(R.string.apk_info_vt_no_api_key)
+        VtStatus.INVALID_API_KEY -> stringResource(R.string.apk_info_vt_invalid_key)
+        // The Retry-After header is optional, so the countdown wording is too.
+        VtStatus.RATE_LIMITED -> vt.errorMessage.takeIf { it.isNotBlank() }
+            ?.let { stringResource(R.string.apk_info_vt_rate_limited_retry, it) }
+            ?: stringResource(R.string.apk_info_vt_rate_limited)
         VtStatus.ERROR -> vt.errorMessage.takeIf { it.isNotBlank() } ?: stringResource(R.string.apk_info_vt_error)
         VtStatus.TOO_LARGE -> stringResource(R.string.apk_info_vt_too_large, vt.errorMessage.orEmpty())
         VtStatus.SCANNING -> stringResource(R.string.apk_info_vt_scanning)
@@ -643,7 +649,7 @@ private fun VirusTotalCard(
             }
             // Telling someone their key is missing is only half an answer — the fix is two
             // screens away and they are mid-install. Offer both steps here.
-            if (status == VtStatus.NO_API_KEY) {
+            if (status == VtStatus.NO_API_KEY || status == VtStatus.INVALID_API_KEY) {
                 Spacer(Modifier.height(8.dp))
                 Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
                     FilledTonalButton(

app/src/main/java/app/pwhs/universalinstaller/presentation/install/InstallViewModel.kt

@@ -1499,7 +1499,15 @@ class InstallViewModel(
                     virusTotalNotifier.notifyUploading(scanNotifId, fileName, pct)
                 }
                 val analysisId = uploadResult.getOrElse { e ->
-                    finishScanWithError(e.message ?: "Upload failed", fileName)
+                    // A rejected key or an exhausted quota is actionable; anything else is not.
+                    if (e is VirusTotalService.VtHttpException) {
+                        finishScan(
+                            VtResult(status = e.vtStatus, errorMessage = e.message.orEmpty()),
+                            fileName,
+                        )
+                    } else {
+                        finishScanWithError(e.message ?: "Upload failed", fileName)
+                    }
                     return@launch
                 }
 

app/src/main/java/app/pwhs/universalinstaller/presentation/install/dialog/DialogMenuContent.kt

@@ -535,6 +535,10 @@ private fun androidx.compose.foundation.lazy.LazyListScope.securityTab(
             VtStatus.QUEUED -> stringResource(R.string.apk_info_vt_queued)
             VtStatus.ANALYZING -> stringResource(R.string.apk_info_vt_analyzing)
             VtStatus.NO_API_KEY -> stringResource(R.string.apk_info_vt_no_api_key)
+            VtStatus.INVALID_API_KEY -> stringResource(R.string.apk_info_vt_invalid_key)
+            VtStatus.RATE_LIMITED -> vtErrorMsg?.takeIf { it.isNotBlank() }
+                ?.let { stringResource(R.string.apk_info_vt_rate_limited_retry, it) }
+                ?: stringResource(R.string.apk_info_vt_rate_limited)
             VtStatus.TOO_LARGE -> stringResource(R.string.apk_info_vt_too_large, vtErrorMsg.orEmpty())
             VtStatus.ERROR -> vtErrorMsg ?: stringResource(R.string.apk_info_vt_error)
             else -> stringResource(R.string.dialog_menu_virustotal_desc)
@@ -547,6 +551,8 @@ private fun androidx.compose.foundation.lazy.LazyListScope.securityTab(
             // and crucially not the neutral grey that made the no-key state invisible.
             VtStatus.SUSPICIOUS,
             VtStatus.NO_API_KEY,
+            VtStatus.INVALID_API_KEY,
+            VtStatus.RATE_LIMITED,
             VtStatus.TOO_LARGE -> extendedColors.warning
             else -> MaterialTheme.colorScheme.onSurfaceVariant
         }
@@ -573,7 +579,8 @@ private fun androidx.compose.foundation.lazy.LazyListScope.securityTab(
                     }
                     // Without a key, tapping Check only rewrites the same "no key" line the user
                     // is already reading. Send them where the key is entered instead.
-                    vtResult?.status == VtStatus.NO_API_KEY -> {
+                    vtResult?.status == VtStatus.NO_API_KEY ||
+                        vtResult?.status == VtStatus.INVALID_API_KEY -> {
                         context.startActivity(
                             android.content.Intent(
                                 context,

app/src/main/res/values-vi/strings.xml

@@ -776,4 +776,7 @@
     <string name="manage_action_installer_source_sub">Cài thủ công / Nguồn không xác định</string>
     <string name="installer_engine_root_request">Nhấn để cấp quyền root</string>
     <string name="dialog_failed_fallback_install">Cài đặt qua trình cài đặt hệ thống</string>
+    <string name="apk_info_vt_invalid_key">VirusTotal từ chối khóa API này. Mở Cài đặt → Advanced → Khóa API VirusTotal và kiểm tra xem đã dán đầy đủ chưa.</string>
+    <string name="apk_info_vt_rate_limited">Đã đạt giới hạn của VirusTotal — gói miễn phí chỉ cho 4 yêu cầu mỗi phút. Hãy thử lại sau giây lát.</string>
+    <string name="apk_info_vt_rate_limited_retry">Đã đạt giới hạn của VirusTotal — gói miễn phí chỉ cho 4 yêu cầu mỗi phút. Hãy thử lại sau %1$s giây.</string>
 </resources>

app/src/main/res/values-zh/strings.xml

@@ -776,4 +776,7 @@
     <string name="setting_security_strict_sub">在文件有扫描结果之前，VirusTotal 扫描会成为主按钮；安装未扫描的文件时会要求确认。需要 API 密钥。</string>
     <string name="setting_vt_strict_check_title">严格的 VirusTotal 检查</string>
     <string name="setting_vt_strict_check_summary">如果文件未扫描，在安装前警告</string>
+    <string name="apk_info_vt_invalid_key">VirusTotal 拒绝了此 API 密钥。请打开“设置”→ Advanced →“VirusTotal API 密钥”，确认已完整粘贴。</string>
+    <string name="apk_info_vt_rate_limited">已达到 VirusTotal 的速率限制 — 免费版每分钟仅允许 4 次请求。请稍后重试。</string>
+    <string name="apk_info_vt_rate_limited_retry">已达到 VirusTotal 的速率限制 — 免费版每分钟仅允许 4 次请求。请在 %1$s 秒后重试。</string>
 </resources>

app/src/main/res/values/strings.xml

@@ -782,4 +782,7 @@
     <string name="manage_action_check_vt_sub">Scan the installed APK</string>
     <string name="manage_action_installer_source">Installed by %1$s</string>
     <string name="manage_action_installer_source_sub">Sideloaded / Unknown source</string>
+    <string name="apk_info_vt_invalid_key">VirusTotal rejected this API key. Open Settings → Advanced → VirusTotal API Key and check it was pasted in full.</string>
+    <string name="apk_info_vt_rate_limited">VirusTotal rate limit reached — the free tier allows 4 requests per minute. Try again shortly.</string>
+    <string name="apk_info_vt_rate_limited_retry">VirusTotal rate limit reached — the free tier allows 4 requests per minute. Try again in %1$s seconds.</string>
 </resources>