fix: user-friendly error messages for API failures

Cross-file error flow audit → fixes:

1. STT layer: parseApiError() extracts human-readable message from JSON
   error bodies (e.g., "Rate limit exceeded" instead of raw JSON blob)

2. ResultPanel: friendlyErrorMessage() now handles HTTP error codes:
   - 401/403 → "Authentication Failed" (check your API key)
   - 429 → "Rate Limited" (wait and retry)
   - 5xx → "Service Unavailable" (try later)

3. Realtime STT: onError now sends 'error' phase to overlay via IPC
   (was silently swallowed with only console.error)

4. i18n: 6 new keys in en.json + zh.json for error messages

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

Author: liangweifeng

electron/ipc-handlers.ts

@@ -155,6 +155,9 @@ export function setupIPC() {
       };
       session.onError = (error) => {
         console.error('[RealtimeSTT] error:', error);
+        if (overlayWC && !overlayWC.isDestroyed()) {
+          overlayWC.send('pipeline:phase', 'error');
+        }
       };
       await session.connect();
       // If user cancelled during connect, don't publish the session

electron/stt-service.ts

@@ -460,6 +460,16 @@ class ParaformerRealtimeSession implements IRealtimeSession {
   }
 }
 
+/** Extract human-readable error from API response body (JSON or plain text) */
+function parseApiError(status: number, body: string): string {
+  try {
+    const json = JSON.parse(body);
+    const msg = json?.error?.message || json?.message || json?.error || '';
+    if (msg) return `${status}: ${typeof msg === 'string' ? msg : JSON.stringify(msg)}`;
+  } catch {}
+  return `${status}: ${body.slice(0, 200)}`;
+}
+
 // ═════════════════════════════════════════════════════════════════════════════
 // STTService — public API
 // ═════════════════════════════════════════════════════════════════════════════
@@ -522,8 +532,7 @@ export class STTService {
     });
 
     if (!res.ok) {
-      const err = await res.text();
-      throw new Error(`DashScope STT ${res.status}: ${err.slice(0, 300)}`);
+      throw new Error(`DashScope STT ${parseApiError(res.status, await res.text().catch(() => ''))}`);
     }
 
     const json = await res.json();
@@ -555,8 +564,7 @@ export class STTService {
     });
 
     if (!res.ok) {
-      const err = await res.text();
-      throw new Error(`STT ${res.status}: ${err.slice(0, 300)}`);
+      throw new Error(`STT ${parseApiError(res.status, await res.text().catch(() => ''))}`);
     }
 
     const json = await res.json();

src/components/recording/ResultPanel.tsx

@@ -16,6 +16,13 @@ function friendlyErrorMessage(error: string, t: (k: string) => string): { title:
     return { title: t('recording.errorTimeout'), detail: t('recording.errorTimeoutDetail') };
   if (lower.includes('pipeline busy'))
     return { title: t('recording.errorBusy'), detail: t('recording.errorBusyDetail') };
+  // HTTP status code errors from API calls
+  if (lower.includes('401') || lower.includes('403') || lower.includes('unauthorized') || lower.includes('forbidden') || lower.includes('invalid'))
+    return { title: t('recording.errorAuth'), detail: t('recording.errorAuthDetail') };
+  if (lower.includes('429') || lower.includes('rate limit'))
+    return { title: t('recording.errorRateLimit'), detail: t('recording.errorRateLimitDetail') };
+  if (/\b5\d\d\b/.test(error) || lower.includes('service unavailable') || lower.includes('bad gateway'))
+    return { title: t('recording.errorServer'), detail: t('recording.errorServerDetail') };
   // Fallback: show technical error
   return { title: t('recording.error'), detail: error };
 }

src/i18n/locales/en.json

@@ -156,7 +156,13 @@
     "errorTimeout": "Request Timed Out",
     "errorTimeoutDetail": "The API took too long to respond. Please try again.",
     "errorBusy": "Processing In Progress",
-    "errorBusyDetail": "Please wait for the current transcription to finish."
+    "errorBusyDetail": "Please wait for the current transcription to finish.",
+    "errorAuth": "Authentication Failed",
+    "errorAuthDetail": "Your API key may be invalid or expired. Please check it in Settings.",
+    "errorRateLimit": "Rate Limited",
+    "errorRateLimitDetail": "Too many requests. Please wait a moment and try again.",
+    "errorServer": "Service Unavailable",
+    "errorServerDetail": "The API service is temporarily down. Please try again later."
   },
   "overlay": {
     "listening": "Listening...",

src/i18n/locales/zh.json

@@ -156,7 +156,13 @@
     "errorTimeout": "请求超时",
     "errorTimeoutDetail": "API 响应时间过长，请稍后重试。",
     "errorBusy": "正在处理中",
-    "errorBusyDetail": "请等待当前转录完成。"
+    "errorBusyDetail": "请等待当前转录完成。",
+    "errorAuth": "认证失败",
+    "errorAuthDetail": "API 密钥可能无效或已过期，请在设置中检查。",
+    "errorRateLimit": "请求频率过高",
+    "errorRateLimitDetail": "请求太频繁，请稍等片刻再试。",
+    "errorServer": "服务暂不可用",
+    "errorServerDetail": "API 服务暂时故障，请稍后再试。"
   },
   "overlay": {
     "listening": "正在收听...",