From 12a00f17024cef90a292bad24f33608a004b3085 Mon Sep 17 00:00:00 2001
From: marcomarcogd <35049765+marcomarcogd@users.noreply.github.com>
Date: Tue, 25 Aug 2026 10:46:09 +0800
Subject: [PATCH] fix(ai): return user-friendly errors across AI features

---
 .../src/components/article/AISearchBar.vue    |   3 +-
 .../modals/settings/ai/AIProfileList.vue      |  10 +-
 .../modals/settings/ai/AIProfileModal.vue     |   5 +-
 frontend/src/composables/ai/useAIProfiles.ts  |   7 +-
 .../composables/article/useArticleSummary.ts  |  16 +-
 frontend/src/i18n/locales/en.ts               |  20 +++
 frontend/src/i18n/locales/zh.ts               |  15 ++
 frontend/src/types/aiProfile.ts               |   1 +
 frontend/src/utils/aiError.ts                 | 118 ++++++++++++++
 internal/ai/deepseek_test.go                  |  43 ++++-
 internal/ai/user_error.go                     | 152 ++++++++++++++++++
 internal/handlers/ai/ai_handlers.go           |  18 ++-
 internal/handlers/ai/ai_profiles_handlers.go  |  18 ++-
 internal/handlers/ai/ai_search.go             |  55 ++++---
 internal/handlers/summary/summary_handlers.go |   5 +-
 .../translation/translation_handlers.go       |  14 +-
 16 files changed, 432 insertions(+), 68 deletions(-)
 create mode 100644 frontend/src/utils/aiError.ts
 create mode 100644 internal/ai/user_error.go

diff --git a/frontend/src/components/article/AISearchBar.vue b/frontend/src/components/article/AISearchBar.vue
index 517f1f24c..97019445e 100644
--- a/frontend/src/components/article/AISearchBar.vue
+++ b/frontend/src/components/article/AISearchBar.vue
@@ -3,6 +3,7 @@ import { ref, computed } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { PhMagnifyingGlass, PhX, PhSparkle, PhSpinner } from '@phosphor-icons/vue';
 import type { Article } from '@/types/models';
+import { getAIErrorMessage } from '@/utils/aiError';
 
 const { t } = useI18n();
 
@@ -37,7 +38,7 @@ async function performAISearch() {
     const data = await response.json();
 
     if (!data.success) {
-      errorMessage.value = data.error || t('aiSearch.searchFailed');
+      errorMessage.value = getAIErrorMessage(data, response.status);
       window.showToast(errorMessage.value, 'error');
       return;
     }
diff --git a/frontend/src/components/modals/settings/ai/AIProfileList.vue b/frontend/src/components/modals/settings/ai/AIProfileList.vue
index ac0c3817b..f0a02e0c7 100644
--- a/frontend/src/components/modals/settings/ai/AIProfileList.vue
+++ b/frontend/src/components/modals/settings/ai/AIProfileList.vue
@@ -15,6 +15,7 @@ import type { AIProfile, AIProfileTestResult, AIProfileFormData } from '@/types/
 import { useAIProfiles } from '@/composables/ai/useAIProfiles';
 import { getProviderIconUrl } from '@/composables/ai/useAIProvider';
 import AIProfileModal from './AIProfileModal.vue';
+import { getAIErrorMessage } from '@/utils/aiError';
 
 const { t } = useI18n();
 const {
@@ -130,6 +131,11 @@ function getTestStatus(profileId: number): 'success' | 'error' | 'unknown' {
   if (!result) return 'unknown';
   return result.config_valid && result.connection_success ? 'success' : 'error';
 }
+
+function getTestError(profileId: number): string {
+  const result = testResults.value.get(profileId);
+  return result ? getAIErrorMessage(result) : '';
+}
 </script>
 
 <template>
@@ -216,7 +222,7 @@ function getTestStatus(profileId: number): 'success' | 'error' | 'unknown' {
             <div
               v-else-if="getTestStatus(profile.id) === 'error'"
               class="status-indicator status-error"
-              :title="testResults.get(profile.id)?.error_message"
+              :title="getTestError(profile.id)"
             >
               <PhX :size="14" class="text-red-500" />
             </div>
@@ -254,7 +260,7 @@ function getTestStatus(profileId: number): 'success' | 'error' | 'unknown' {
           v-if="testResults.get(profile.id)?.error_message && getTestStatus(profile.id) === 'error'"
           class="mt-2 text-xs text-red-500 bg-red-500/5 rounded p-2 break-words"
         >
-          {{ testResults.get(profile.id)?.error_message }}
+          {{ getTestError(profile.id) }}
         </div>
       </div>
     </div>
diff --git a/frontend/src/components/modals/settings/ai/AIProfileModal.vue b/frontend/src/components/modals/settings/ai/AIProfileModal.vue
index 6aab4d5a9..c91e61963 100644
--- a/frontend/src/components/modals/settings/ai/AIProfileModal.vue
+++ b/frontend/src/components/modals/settings/ai/AIProfileModal.vue
@@ -17,6 +17,7 @@ import type { AIProfileFormData, AIProfileTestResult } from '@/types/aiProfile';
 import type { Status } from '@/components/settings/base/StatusBox.vue';
 import { defaultAIProfileFormData } from '@/types/aiProfile';
 import { useAIProfiles } from '@/composables/ai/useAIProfiles';
+import { getAIErrorMessage } from '@/utils/aiError';
 import { openInBrowser } from '@/utils/browser';
 
 const { t, locale } = useI18n();
@@ -105,7 +106,7 @@ async function testConfiguration() {
     if (result) {
       testResult.value = result;
       if (!result.config_valid || !result.connection_success) {
-        testError.value = result.error_message || t('setting.ai.aiTestFailed');
+        testError.value = getAIErrorMessage(result);
       }
     } else {
       testError.value = t('setting.ai.aiTestFailed');
@@ -155,7 +156,7 @@ async function saveProfile() {
     }
   } catch (e) {
     console.error('Save failed:', e);
-    saveError.value = e instanceof Error ? e.message : t('setting.ai.saveFailed');
+    saveError.value = getAIErrorMessage(e);
   } finally {
     isSaving.value = false;
   }
diff --git a/frontend/src/composables/ai/useAIProfiles.ts b/frontend/src/composables/ai/useAIProfiles.ts
index 2f338d1a5..b101e023e 100644
--- a/frontend/src/composables/ai/useAIProfiles.ts
+++ b/frontend/src/composables/ai/useAIProfiles.ts
@@ -1,6 +1,7 @@
 import { ref, computed } from 'vue';
 import type { AIProfile, AIProfileTestResult, AIProfileFormData } from '@/types/aiProfile';
 import { defaultAIProfileFormData } from '@/types/aiProfile';
+import { readAIError } from '@/utils/aiError';
 
 // Shared state for AI profiles
 const profiles = ref<AIProfile[]>([]);
@@ -59,8 +60,7 @@ export function useAIProfiles() {
       });
 
       if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(errorText || `Failed to create profile: ${response.status}`);
+        throw new Error((await readAIError(response)).message);
       }
 
       const newProfile = await response.json();
@@ -82,8 +82,7 @@ export function useAIProfiles() {
       });
 
       if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(errorText || `Failed to update profile: ${response.status}`);
+        throw new Error((await readAIError(response)).message);
       }
 
       const updatedProfile = await response.json();
diff --git a/frontend/src/composables/article/useArticleSummary.ts b/frontend/src/composables/article/useArticleSummary.ts
index 15e68bf76..bb742d628 100644
--- a/frontend/src/composables/article/useArticleSummary.ts
+++ b/frontend/src/composables/article/useArticleSummary.ts
@@ -1,6 +1,7 @@
 import { ref, type Ref } from 'vue';
 import { useI18n } from 'vue-i18n';
 import type { Article } from '@/types/models';
+import { getAIErrorMessage, readAIError } from '@/utils/aiError';
 
 interface SummarySettings {
   enabled: boolean;
@@ -116,18 +117,7 @@ export function useArticleSummary() {
 
         return data;
       } else {
-        // Handle API errors properly
-        let errorMessage = `${t('setting.content.summaryGenerationFailed')}: ${res.status} ${res.statusText}`;
-
-        try {
-          const errorData = await res.json();
-          if (errorData.error) {
-            errorMessage = errorData.error;
-          }
-        } catch (jsonError) {
-          // If we can't parse JSON, use the status text
-          console.error('Error parsing error response:', jsonError);
-        }
+        const { message: errorMessage } = await readAIError(res);
 
         console.error('Summary generation failed:', errorMessage);
 
@@ -148,7 +138,7 @@ export function useArticleSummary() {
         return null;
       }
 
-      const errorMessage = `${t('setting.content.summaryGenerationFailed')}: ${e instanceof Error ? e.message : t('common.errors.unknownError')}`;
+      const errorMessage = getAIErrorMessage(e);
       console.error('Error generating summary:', e);
 
       // Cache the error to show in UI
diff --git a/frontend/src/i18n/locales/en.ts b/frontend/src/i18n/locales/en.ts
index 78901587b..eaf5288fb 100644
--- a/frontend/src/i18n/locales/en.ts
+++ b/frontend/src/i18n/locales/en.ts
@@ -146,6 +146,26 @@ const en: TranslationMessages = {
     searchFailed: 'AI search failed. Please check your AI settings.',
     showingResults: 'Showing AI search results',
   },
+  aiErrors: {
+    configuration_invalid:
+      'The AI configuration is incomplete or invalid. Check the endpoint and model.',
+    usage_limit_reached:
+      'The AI usage limit configured in MrRSS has been reached. Adjust it and try again.',
+    rate_limited: 'The AI service is receiving too many requests. Please try again later.',
+    authentication_failed: 'AI authentication failed. Check the API key and access permissions.',
+    payment_required:
+      'The AI service has insufficient quota or balance. Check the provider account.',
+    model_or_endpoint_not_found:
+      'The AI model or endpoint is unavailable. Check the configuration.',
+    request_too_large: 'The content sent to AI is too large. Shorten it or choose another model.',
+    timeout: 'The AI service response timed out. Please try again.',
+    network_error: 'Could not reach the AI service. Check the network, proxy, and endpoint.',
+    provider_unavailable: 'The AI service is temporarily unavailable. Please try again later.',
+    invalid_response: 'The AI service returned an invalid response. Retry or choose another model.',
+    provider_rejected_request:
+      'The AI service rejected the request. Check the model and endpoint settings.',
+    request_failed: 'The AI request failed. Check the AI configuration and try again.',
+  },
   common: {
     cancel: 'Cancel',
     confirm: 'Confirm',
diff --git a/frontend/src/i18n/locales/zh.ts b/frontend/src/i18n/locales/zh.ts
index 8bc59a006..22b742556 100644
--- a/frontend/src/i18n/locales/zh.ts
+++ b/frontend/src/i18n/locales/zh.ts
@@ -141,6 +141,21 @@ const zh: TranslationMessages = {
     searchFailed: 'AI 搜索失败，请检查 AI 设置。',
     showingResults: '正在显示 AI 搜索结果',
   },
+  aiErrors: {
+    configuration_invalid: 'AI 配置不完整或无效，请检查接口地址和模型。',
+    usage_limit_reached: '已达到 MrRSS 设置的 AI 使用上限，请调整上限后重试。',
+    rate_limited: 'AI 服务请求过于频繁，请稍后再试。',
+    authentication_failed: 'AI 服务鉴权失败，请检查 API Key 和访问权限。',
+    payment_required: 'AI 服务额度不足，请检查服务商账户余额。',
+    model_or_endpoint_not_found: 'AI 模型或接口地址不可用，请检查配置。',
+    request_too_large: '发送给 AI 的内容过长，请缩短内容或更换模型。',
+    timeout: 'AI 服务响应超时，请稍后重试。',
+    network_error: '无法连接 AI 服务，请检查网络、代理和接口地址。',
+    provider_unavailable: 'AI 服务暂时不可用，请稍后重试。',
+    invalid_response: 'AI 服务返回内容格式异常，请重试或更换模型。',
+    provider_rejected_request: 'AI 服务拒绝了请求，请检查模型和接口配置。',
+    request_failed: 'AI 请求失败，请检查 AI 配置后重试。',
+  },
   common: {
     cancel: '取消',
     confirm: '确认',
diff --git a/frontend/src/types/aiProfile.ts b/frontend/src/types/aiProfile.ts
index 80a2dc871..a46e68f9f 100644
--- a/frontend/src/types/aiProfile.ts
+++ b/frontend/src/types/aiProfile.ts
@@ -22,6 +22,7 @@ export interface AIProfileTestResult {
   model_available: boolean;
   response_time_ms: number;
   error_message?: string;
+  error_code?: string;
 }
 
 export interface AIProfileFormData {
diff --git a/frontend/src/utils/aiError.ts b/frontend/src/utils/aiError.ts
new file mode 100644
index 000000000..d3a848cc0
--- /dev/null
+++ b/frontend/src/utils/aiError.ts
@@ -0,0 +1,118 @@
+import i18n from '@/i18n';
+
+export interface ParsedAIError {
+  code: string;
+  message: string;
+  payload?: unknown;
+}
+
+const knownCodes = new Set([
+  'configuration_invalid',
+  'usage_limit_reached',
+  'rate_limited',
+  'authentication_failed',
+  'payment_required',
+  'model_or_endpoint_not_found',
+  'request_too_large',
+  'timeout',
+  'network_error',
+  'provider_unavailable',
+  'invalid_response',
+  'provider_rejected_request',
+  'request_failed',
+]);
+
+const legacyCodeAliases: Record<string, string> = {
+  AI_CONFIG_FAILED: 'configuration_invalid',
+  AI_QUOTA_EXCEEDED: 'rate_limited',
+  AI_INVALID_REQUEST: 'provider_rejected_request',
+  AI_REQUEST_FAILED: 'request_failed',
+};
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' ? (value as Record<string, unknown>) : null;
+}
+
+function payloadCode(payload: unknown): string {
+  const record = asRecord(payload);
+  if (!record) return '';
+  const error = asRecord(record.error);
+  const candidate = record.error_code ?? error?.code ?? record.code;
+  if (typeof candidate !== 'string') return '';
+  return legacyCodeAliases[candidate] || candidate.toLowerCase();
+}
+
+function payloadText(payload: unknown): string {
+  if (typeof payload === 'string') return payload;
+  if (payload instanceof Error) return payload.message;
+  const record = asRecord(payload);
+  if (!record) return '';
+  const error = asRecord(record.error);
+  const values = [record.error, error?.message, record.message];
+  return values.find((value): value is string => typeof value === 'string') || '';
+}
+
+function inferCode(payload: unknown, status?: number): string {
+  const explicit = payloadCode(payload);
+  if (knownCodes.has(explicit)) return explicit;
+
+  switch (status) {
+    case 401:
+    case 403:
+      return 'authentication_failed';
+    case 402:
+      return 'payment_required';
+    case 404:
+      return 'model_or_endpoint_not_found';
+    case 408:
+    case 504:
+      return 'timeout';
+    case 413:
+      return 'request_too_large';
+    case 429:
+      return 'rate_limited';
+    default:
+      if (status && status >= 500) return 'provider_unavailable';
+  }
+
+  const text = payloadText(payload).toLowerCase();
+  if (/\b429\b|rate.?limit|too many requests/.test(text)) return 'rate_limited';
+  if (/\b401\b|\b403\b|unauthori[sz]ed|forbidden|invalid api.?key|authentication/.test(text)) {
+    return 'authentication_failed';
+  }
+  if (/\b402\b|insufficient (quota|balance)|payment required|credit/.test(text)) {
+    return 'payment_required';
+  }
+  if (/\b404\b|model.*not found|endpoint.*not found/.test(text)) {
+    return 'model_or_endpoint_not_found';
+  }
+  if (/\b413\b|request.*too large|context length/.test(text)) return 'request_too_large';
+  if (/timeout|timed out|deadline exceeded/.test(text)) return 'timeout';
+  if (/connection refused|network|no such host|failed to fetch/.test(text)) return 'network_error';
+  if (/invalid json|invalid response|empty response|no choices/.test(text))
+    return 'invalid_response';
+  return 'request_failed';
+}
+
+export function getAIErrorMessage(payload: unknown, status?: number): string {
+  const code = inferCode(payload, status);
+  return String(i18n.global.t(`aiErrors.${code}`));
+}
+
+export async function readAIError(response: Response): Promise<ParsedAIError> {
+  let raw = '';
+  try {
+    raw = await response.text();
+  } catch {
+    // A response body is optional; the HTTP status still provides a stable
+    // classification without exposing transport details.
+  }
+  let payload: unknown;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    payload = raw;
+  }
+  const code = inferCode(payload, response.status);
+  return { code, message: getAIErrorMessage(payload, response.status), payload };
+}
diff --git a/internal/ai/deepseek_test.go b/internal/ai/deepseek_test.go
index a80a97769..e1aeae8de 100644
--- a/internal/ai/deepseek_test.go
+++ b/internal/ai/deepseek_test.go
@@ -1,6 +1,12 @@
 package ai
 
-import "testing"
+import (
+	"context"
+	"errors"
+	"net"
+	"strings"
+	"testing"
+)
 
 func TestDeepSeekFormatEndpointNormalizesBaseURLs(t *testing.T) {
 	handler := &DeepSeekHandler{}
@@ -45,3 +51,38 @@ func TestDeepSeekFormatEndpointNormalizesBaseURLs(t *testing.T) {
 		})
 	}
 }
+
+func TestClassifyUserFacingErrorDoesNotExposeProviderResponse(t *testing.T) {
+	const secret = `{"error":{"message":"provider detail sk-secret-value"}}`
+	tests := []struct {
+		name string
+		err  error
+		code string
+	}{
+		{name: "authentication", err: errors.New("OpenAI API returned status 401: " + secret), code: ErrorCodeAuthenticationFailed},
+		{name: "payment", err: errors.New("OpenAI API returned status 402: " + secret), code: ErrorCodePaymentRequired},
+		{name: "not found", err: errors.New("OpenAI API returned status 404: " + secret), code: ErrorCodeModelOrEndpointNotFound},
+		{name: "too large", err: errors.New("OpenAI API returned status 413: " + secret), code: ErrorCodeRequestTooLarge},
+		{name: "rate limited", err: errors.New("OpenAI API returned status 429: " + secret), code: ErrorCodeRateLimited},
+		{name: "provider unavailable", err: errors.New("OpenAI API returned status 503: " + secret), code: ErrorCodeProviderUnavailable},
+		{name: "timeout", err: context.DeadlineExceeded, code: ErrorCodeTimeout},
+		{name: "network", err: &net.DNSError{Err: "no such host", Name: "private.example"}, code: ErrorCodeNetwork},
+		{name: "invalid response", err: errors.New("invalid JSON response"), code: ErrorCodeInvalidResponse},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ClassifyUserFacingError(tt.err)
+			if got.Code != tt.code {
+				t.Fatalf("code = %q, want %q", got.Code, tt.code)
+			}
+			if got.Message == "" || strings.Contains(got.Message, "sk-secret-value") || strings.Contains(got.Message, "provider detail") {
+				t.Fatalf("unsafe user-facing message: %q", got.Message)
+			}
+		})
+	}
+
+	if got := RedactEndpoint("https://user:secret@api.example.com/v1/chat?token=secret#fragment"); got != "https://api.example.com/v1/chat" {
+		t.Fatalf("RedactEndpoint leaked or changed the endpoint: %q", got)
+	}
+}
diff --git a/internal/ai/user_error.go b/internal/ai/user_error.go
new file mode 100644
index 000000000..0cf187f99
--- /dev/null
+++ b/internal/ai/user_error.go
@@ -0,0 +1,152 @@
+package ai
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+const (
+	ErrorCodeConfigurationInvalid    = "configuration_invalid"
+	ErrorCodeUsageLimitReached       = "usage_limit_reached"
+	ErrorCodeRateLimited             = "rate_limited"
+	ErrorCodeAuthenticationFailed    = "authentication_failed"
+	ErrorCodePaymentRequired         = "payment_required"
+	ErrorCodeModelOrEndpointNotFound = "model_or_endpoint_not_found"
+	ErrorCodeRequestTooLarge         = "request_too_large"
+	ErrorCodeTimeout                 = "timeout"
+	ErrorCodeNetwork                 = "network_error"
+	ErrorCodeProviderUnavailable     = "provider_unavailable"
+	ErrorCodeInvalidResponse         = "invalid_response"
+	ErrorCodeProviderRejectedRequest = "provider_rejected_request"
+	ErrorCodeRequestFailed           = "request_failed"
+)
+
+// UserFacingError is safe to expose over the HTTP API. It deliberately keeps
+// provider response bodies and request credentials out of user-visible text.
+type UserFacingError struct {
+	Code       string
+	Message    string
+	HTTPStatus int
+}
+
+// RedactEndpoint keeps only the non-sensitive origin and path for diagnostic
+// logs. Userinfo, query parameters, and fragments may contain API credentials.
+func RedactEndpoint(raw string) string {
+	parsed, err := url.Parse(strings.TrimSpace(raw))
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return "configured endpoint"
+	}
+	parsed.User = nil
+	parsed.RawQuery = ""
+	parsed.Fragment = ""
+	return parsed.String()
+}
+
+// ClassifyUserFacingError converts provider, transport, and response parsing
+// failures into a stable public code and a short, non-sensitive message.
+func ClassifyUserFacingError(err error) UserFacingError {
+	if err == nil {
+		return userFacingError(ErrorCodeRequestFailed)
+	}
+	if errors.Is(err, context.DeadlineExceeded) {
+		return userFacingError(ErrorCodeTimeout)
+	}
+	if errors.Is(err, context.Canceled) {
+		return userFacingError(ErrorCodeRequestFailed)
+	}
+
+	message := strings.ToLower(err.Error())
+	if statusCode := providerStatusCode(message); statusCode > 0 {
+		switch {
+		case statusCode == http.StatusTooManyRequests:
+			return userFacingError(ErrorCodeRateLimited)
+		case statusCode == http.StatusUnauthorized || statusCode == http.StatusForbidden:
+			return userFacingError(ErrorCodeAuthenticationFailed)
+		case statusCode == http.StatusPaymentRequired:
+			return userFacingError(ErrorCodePaymentRequired)
+		case statusCode == http.StatusNotFound:
+			return userFacingError(ErrorCodeModelOrEndpointNotFound)
+		case statusCode == http.StatusRequestEntityTooLarge:
+			return userFacingError(ErrorCodeRequestTooLarge)
+		case statusCode >= http.StatusInternalServerError:
+			return userFacingError(ErrorCodeProviderUnavailable)
+		case statusCode >= http.StatusBadRequest:
+			return userFacingError(ErrorCodeProviderRejectedRequest)
+		}
+	}
+
+	var networkErr net.Error
+	if errors.As(err, &networkErr) {
+		if networkErr.Timeout() {
+			return userFacingError(ErrorCodeTimeout)
+		}
+		return userFacingError(ErrorCodeNetwork)
+	}
+
+	switch {
+	case strings.Contains(message, "usage limit"), strings.Contains(message, "token limit"):
+		return userFacingError(ErrorCodeUsageLimitReached)
+	case strings.Contains(message, "timeout"), strings.Contains(message, "deadline exceeded"):
+		return userFacingError(ErrorCodeTimeout)
+	case strings.Contains(message, "connection refused"), strings.Contains(message, "no such host"), strings.Contains(message, "network is unreachable"):
+		return userFacingError(ErrorCodeNetwork)
+	case strings.Contains(message, "invalid json"), strings.Contains(message, "decode"), strings.Contains(message, "empty response"), strings.Contains(message, "empty content"), strings.Contains(message, "no choices"):
+		return userFacingError(ErrorCodeInvalidResponse)
+	default:
+		return userFacingError(ErrorCodeRequestFailed)
+	}
+}
+
+var providerStatusPattern = regexp.MustCompile(`(?i)(?:status|http)[^0-9]{0,12}([1-5][0-9]{2})`)
+
+func providerStatusCode(message string) int {
+	match := providerStatusPattern.FindStringSubmatch(message)
+	if len(match) != 2 {
+		return 0
+	}
+	statusCode, _ := strconv.Atoi(match[1])
+	return statusCode
+}
+
+// UserFacingErrorForCode returns the canonical safe message and HTTP status
+// for an explicitly detected application error.
+func UserFacingErrorForCode(code string) UserFacingError {
+	return userFacingError(code)
+}
+
+func userFacingError(code string) UserFacingError {
+	switch code {
+	case ErrorCodeConfigurationInvalid:
+		return UserFacingError{Code: code, Message: "AI configuration is incomplete or invalid", HTTPStatus: http.StatusBadRequest}
+	case ErrorCodeUsageLimitReached:
+		return UserFacingError{Code: code, Message: "The configured AI usage limit has been reached", HTTPStatus: http.StatusTooManyRequests}
+	case ErrorCodeRateLimited:
+		return UserFacingError{Code: code, Message: "The AI service is receiving too many requests", HTTPStatus: http.StatusTooManyRequests}
+	case ErrorCodeAuthenticationFailed:
+		return UserFacingError{Code: code, Message: "AI service authentication failed", HTTPStatus: http.StatusUnauthorized}
+	case ErrorCodePaymentRequired:
+		return UserFacingError{Code: code, Message: "The AI service account has insufficient quota or balance", HTTPStatus: http.StatusPaymentRequired}
+	case ErrorCodeModelOrEndpointNotFound:
+		return UserFacingError{Code: code, Message: "The configured AI model or endpoint was not found", HTTPStatus: http.StatusNotFound}
+	case ErrorCodeRequestTooLarge:
+		return UserFacingError{Code: code, Message: "The AI request is too large for the configured service", HTTPStatus: http.StatusRequestEntityTooLarge}
+	case ErrorCodeTimeout:
+		return UserFacingError{Code: code, Message: "The AI service response timed out", HTTPStatus: http.StatusGatewayTimeout}
+	case ErrorCodeNetwork:
+		return UserFacingError{Code: code, Message: "MRSS could not connect to the AI service", HTTPStatus: http.StatusBadGateway}
+	case ErrorCodeProviderUnavailable:
+		return UserFacingError{Code: code, Message: "The AI service is temporarily unavailable", HTTPStatus: http.StatusBadGateway}
+	case ErrorCodeInvalidResponse:
+		return UserFacingError{Code: code, Message: "The AI service returned an invalid response", HTTPStatus: http.StatusBadGateway}
+	case ErrorCodeProviderRejectedRequest:
+		return UserFacingError{Code: code, Message: "The AI service rejected the request", HTTPStatus: http.StatusBadRequest}
+	default:
+		return UserFacingError{Code: ErrorCodeRequestFailed, Message: "The AI request failed", HTTPStatus: http.StatusBadGateway}
+	}
+}
diff --git a/internal/handlers/ai/ai_handlers.go b/internal/handlers/ai/ai_handlers.go
index 1d959341e..3d265a07c 100644
--- a/internal/handlers/ai/ai_handlers.go
+++ b/internal/handlers/ai/ai_handlers.go
@@ -21,6 +21,7 @@ type TestResult struct {
 	ResponseTimeMs    int64  `json:"response_time_ms"`
 	TestTime          string `json:"test_time"`
 	ErrorMessage      string `json:"error_message,omitempty"`
+	ErrorCode         string `json:"error_code,omitempty"`
 }
 
 // HandleTestAIConfig handles POST /api/ai/test to test AI configuration
@@ -71,7 +72,8 @@ func HandleTestAIConfig(h *core.Handler, w http.ResponseWriter, r *http.Request)
 	}
 
 	if !result.ConfigValid {
-		result.ErrorMessage = "Configuration incomplete: " + strings.Join(validationErrors, ", ")
+		result.ErrorMessage = ai.UserFacingErrorForCode(ai.ErrorCodeConfigurationInvalid).Message
+		result.ErrorCode = ai.ErrorCodeConfigurationInvalid
 		response.JSON(w, result)
 		return
 	}
@@ -80,7 +82,8 @@ func HandleTestAIConfig(h *core.Handler, w http.ResponseWriter, r *http.Request)
 	parsedURL, err := url.Parse(endpoint)
 	if err != nil {
 		result.ConfigValid = false
-		result.ErrorMessage = "Invalid endpoint URL: " + err.Error()
+		result.ErrorMessage = ai.UserFacingErrorForCode(ai.ErrorCodeConfigurationInvalid).Message
+		result.ErrorCode = ai.ErrorCodeConfigurationInvalid
 		response.JSON(w, result)
 		return
 	}
@@ -88,7 +91,8 @@ func HandleTestAIConfig(h *core.Handler, w http.ResponseWriter, r *http.Request)
 	// Both HTTP and HTTPS are allowed
 	if parsedURL.Scheme != "http" && parsedURL.Scheme != "https" {
 		result.ConfigValid = false
-		result.ErrorMessage = "API endpoint must use HTTP or HTTPS"
+		result.ErrorMessage = ai.UserFacingErrorForCode(ai.ErrorCodeConfigurationInvalid).Message
+		result.ErrorCode = ai.ErrorCodeConfigurationInvalid
 		response.JSON(w, result)
 		return
 	}
@@ -99,9 +103,11 @@ func HandleTestAIConfig(h *core.Handler, w http.ResponseWriter, r *http.Request)
 	// Create HTTP client with proxy support if configured
 	httpClient, err := createHTTPClientWithProxy(h)
 	if err != nil {
+		publicErr := ai.ClassifyUserFacingError(err)
 		result.ConnectionSuccess = false
 		result.ModelAvailable = false
-		result.ErrorMessage = fmt.Sprintf("Failed to create HTTP client: %v", err)
+		result.ErrorMessage = publicErr.Message
+		result.ErrorCode = publicErr.Code
 		result.ResponseTimeMs = time.Since(startTime).Milliseconds()
 		response.JSON(w, result)
 		return
@@ -121,9 +127,11 @@ func HandleTestAIConfig(h *core.Handler, w http.ResponseWriter, r *http.Request)
 	_, err = client.Request("", "test")
 
 	if err != nil {
+		publicErr := ai.ClassifyUserFacingError(err)
 		result.ConnectionSuccess = false
 		result.ModelAvailable = false
-		result.ErrorMessage = fmt.Sprintf("Connection failed: %v", err)
+		result.ErrorMessage = publicErr.Message
+		result.ErrorCode = publicErr.Code
 	} else {
 		result.ConnectionSuccess = true
 		result.ModelAvailable = true
diff --git a/internal/handlers/ai/ai_profiles_handlers.go b/internal/handlers/ai/ai_profiles_handlers.go
index b71167787..a4384bb23 100644
--- a/internal/handlers/ai/ai_profiles_handlers.go
+++ b/internal/handlers/ai/ai_profiles_handlers.go
@@ -44,6 +44,7 @@ type ProfileTestResult struct {
 	ModelAvailable    bool   `json:"model_available"`
 	ResponseTimeMs    int64  `json:"response_time_ms"`
 	ErrorMessage      string `json:"error_message,omitempty"`
+	ErrorCode         string `json:"error_code,omitempty"`
 }
 
 // HandleListAIProfiles handles GET /api/ai/profiles
@@ -477,7 +478,8 @@ func testAIProfileConnection(h *core.Handler, profile *models.AIProfile) Profile
 	}
 
 	if !result.ConfigValid {
-		result.ErrorMessage = "Configuration incomplete: " + strings.Join(validationErrors, ", ")
+		result.ErrorMessage = ai.UserFacingErrorForCode(ai.ErrorCodeConfigurationInvalid).Message
+		result.ErrorCode = ai.ErrorCodeConfigurationInvalid
 		result.ResponseTimeMs = time.Since(startTime).Milliseconds()
 		return result
 	}
@@ -486,14 +488,16 @@ func testAIProfileConnection(h *core.Handler, profile *models.AIProfile) Profile
 	parsedURL, err := url.Parse(profile.Endpoint)
 	if err != nil {
 		result.ConfigValid = false
-		result.ErrorMessage = "Invalid endpoint URL: " + err.Error()
+		result.ErrorMessage = ai.UserFacingErrorForCode(ai.ErrorCodeConfigurationInvalid).Message
+		result.ErrorCode = ai.ErrorCodeConfigurationInvalid
 		result.ResponseTimeMs = time.Since(startTime).Milliseconds()
 		return result
 	}
 
 	if parsedURL.Scheme != "http" && parsedURL.Scheme != "https" {
 		result.ConfigValid = false
-		result.ErrorMessage = "API endpoint must use HTTP or HTTPS"
+		result.ErrorMessage = ai.UserFacingErrorForCode(ai.ErrorCodeConfigurationInvalid).Message
+		result.ErrorCode = ai.ErrorCodeConfigurationInvalid
 		result.ResponseTimeMs = time.Since(startTime).Milliseconds()
 		return result
 	}
@@ -501,9 +505,11 @@ func testAIProfileConnection(h *core.Handler, profile *models.AIProfile) Profile
 	// Create HTTP client with proxy support if configured
 	httpClient, err := createHTTPClientWithProxyForProfile(h)
 	if err != nil {
+		publicErr := ai.ClassifyUserFacingError(err)
 		result.ConnectionSuccess = false
 		result.ModelAvailable = false
-		result.ErrorMessage = fmt.Sprintf("Failed to create HTTP client: %v", err)
+		result.ErrorMessage = publicErr.Message
+		result.ErrorCode = publicErr.Code
 		result.ResponseTimeMs = time.Since(startTime).Milliseconds()
 		return result
 	}
@@ -524,9 +530,11 @@ func testAIProfileConnection(h *core.Handler, profile *models.AIProfile) Profile
 	_, err = client.Request("", "test")
 
 	if err != nil {
+		publicErr := ai.ClassifyUserFacingError(err)
 		result.ConnectionSuccess = false
 		result.ModelAvailable = false
-		result.ErrorMessage = fmt.Sprintf("Connection failed: %v", err)
+		result.ErrorMessage = publicErr.Message
+		result.ErrorCode = publicErr.Code
 	} else {
 		result.ConnectionSuccess = true
 		result.ModelAvailable = true
diff --git a/internal/handlers/ai/ai_search.go b/internal/handlers/ai/ai_search.go
index 1601f6bbc..e745605fe 100644
--- a/internal/handlers/ai/ai_search.go
+++ b/internal/handlers/ai/ai_search.go
@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"log"
 	"net/http"
-	"net/url"
 	"regexp"
 	"strings"
 	"time"
@@ -29,6 +28,7 @@ type AISearchResponse struct {
 	SearchTerms   string           `json:"search_terms,omitempty"`
 	ExpandedTerms *SearchTerms     `json:"expanded_terms,omitempty"`
 	Error         string           `json:"error,omitempty"`
+	ErrorCode     string           `json:"error_code,omitempty"`
 	TotalCount    int              `json:"total_count"`
 }
 
@@ -99,18 +99,6 @@ func normalizeSearchPatterns(values []string, max int) []string {
 	return result
 }
 
-func endpointForLog(rawEndpoint string) string {
-	parsed, err := url.Parse(strings.TrimSpace(rawEndpoint))
-	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
-		return "<configured>"
-	}
-	parsed.User = nil
-	parsed.RawQuery = ""
-	parsed.ForceQuery = false
-	parsed.Fragment = ""
-	return parsed.String()
-}
-
 func normalizeTerms(values []string, max int) []string {
 	result := make([]string, 0, len(values))
 	seen := make(map[string]struct{})
@@ -176,16 +164,18 @@ func HandleAISearch(h *core.Handler, w http.ResponseWriter, r *http.Request) {
 	var req AISearchRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 		response.JSON(w, AISearchResponse{
-			Success: false,
-			Error:   "Invalid request format",
+			Success:   false,
+			Error:     "Invalid search request",
+			ErrorCode: ai.ErrorCodeProviderRejectedRequest,
 		})
 		return
 	}
 
 	if strings.TrimSpace(req.Query) == "" {
 		response.JSON(w, AISearchResponse{
-			Success: false,
-			Error:   "Search query is required",
+			Success:   false,
+			Error:     "Search query is required",
+			ErrorCode: ai.ErrorCodeProviderRejectedRequest,
 		})
 		return
 	}
@@ -201,7 +191,7 @@ func HandleAISearch(h *core.Handler, w http.ResponseWriter, r *http.Request) {
 			apiKey = cfg.APIKey
 			endpoint = cfg.Endpoint
 			model = cfg.Model
-			log.Printf("[AI Search] Using AI profile for search (endpoint: %s, model: %s)", endpointForLog(endpoint), model)
+			log.Printf("[AI Search] Using AI profile for search (endpoint: %s, model: %s)", ai.RedactEndpoint(endpoint), model)
 		}
 	}
 
@@ -219,14 +209,15 @@ func HandleAISearch(h *core.Handler, w http.ResponseWriter, r *http.Request) {
 		if model == "" {
 			model = defaults.AIModel
 		}
-		log.Printf("[AI Search] Using global AI settings for search (endpoint: %s, model: %s)", endpointForLog(endpoint), model)
+		log.Printf("[AI Search] Using global AI settings for search (endpoint: %s, model: %s)", ai.RedactEndpoint(endpoint), model)
 	}
 
 	// Validate AI configuration
 	if endpoint == "" || model == "" {
 		response.JSON(w, AISearchResponse{
-			Success: false,
-			Error:   "AI is not configured. Please configure AI settings first.",
+			Success:   false,
+			Error:     ai.UserFacingErrorForCode(ai.ErrorCodeConfigurationInvalid).Message,
+			ErrorCode: ai.ErrorCodeConfigurationInvalid,
 		})
 		return
 	}
@@ -234,9 +225,11 @@ func HandleAISearch(h *core.Handler, w http.ResponseWriter, r *http.Request) {
 	// Create AI client
 	httpClient, err := createHTTPClientWithProxy(h)
 	if err != nil {
+		publicErr := ai.ClassifyUserFacingError(err)
 		response.JSON(w, AISearchResponse{
-			Success: false,
-			Error:   fmt.Sprintf("Failed to create HTTP client: %v", err),
+			Success:   false,
+			Error:     publicErr.Message,
+			ErrorCode: publicErr.Code,
 		})
 		return
 	}
@@ -254,9 +247,12 @@ func HandleAISearch(h *core.Handler, w http.ResponseWriter, r *http.Request) {
 	systemPrompt := buildAISearchPrompt()
 	aiResponse, err := client.Request(systemPrompt, req.Query)
 	if err != nil {
+		publicErr := ai.ClassifyUserFacingError(err)
+		log.Printf("[AI Search] Request failed code=%s status=%d", publicErr.Code, publicErr.HTTPStatus)
 		response.JSON(w, AISearchResponse{
-			Success: false,
-			Error:   fmt.Sprintf("AI request failed: %v", err),
+			Success:   false,
+			Error:     publicErr.Message,
+			ErrorCode: publicErr.Code,
 		})
 		return
 	}
@@ -264,9 +260,11 @@ func HandleAISearch(h *core.Handler, w http.ResponseWriter, r *http.Request) {
 	// Parse search terms from AI response
 	searchTerms, err := parseSearchTermsAdvanced(aiResponse)
 	if err != nil {
+		publicErr := ai.UserFacingErrorForCode(ai.ErrorCodeInvalidResponse)
 		response.JSON(w, AISearchResponse{
-			Success: false,
-			Error:   fmt.Sprintf("Failed to parse search terms: %v", err),
+			Success:   false,
+			Error:     publicErr.Message,
+			ErrorCode: publicErr.Code,
 		})
 		return
 	}
@@ -294,7 +292,8 @@ func HandleAISearch(h *core.Handler, w http.ResponseWriter, r *http.Request) {
 		log.Printf("[AI Search] Query error: %v", err)
 		response.JSON(w, AISearchResponse{
 			Success:     false,
-			Error:       fmt.Sprintf("Search query failed: %v", err),
+			Error:       "The article search could not be completed",
+			ErrorCode:   ai.ErrorCodeRequestFailed,
 			SearchTerms: strings.Join(allTerms, ", "),
 		})
 		return
diff --git a/internal/handlers/summary/summary_handlers.go b/internal/handlers/summary/summary_handlers.go
index f3fac4012..cb1f41401 100644
--- a/internal/handlers/summary/summary_handlers.go
+++ b/internal/handlers/summary/summary_handlers.go
@@ -149,7 +149,7 @@ func HandleSummarizeArticle(h *core.Handler, w http.ResponseWriter, r *http.Requ
 					apiKey = cfg.APIKey
 					endpoint = cfg.Endpoint
 					model = cfg.Model
-					log.Printf("Using AI profile for summarization (endpoint: %s, model: %s)", endpoint, model)
+					log.Printf("AI summary profile selected endpoint=%s model=%s", ai.RedactEndpoint(endpoint), model)
 				}
 			}
 
@@ -182,7 +182,8 @@ func HandleSummarizeArticle(h *core.Handler, w http.ResponseWriter, r *http.Requ
 			}
 			aiResult, err := aiSummarizer.Summarize(content, summaryLength)
 			if err != nil {
-				log.Printf("Error generating AI summary, falling back to local: %v", err)
+				publicErr := ai.ClassifyUserFacingError(err)
+				log.Printf("AI summary failed code=%s status=%d; using local fallback", publicErr.Code, publicErr.HTTPStatus)
 				// Fallback to local algorithm on any AI error
 				summarizer := summary.NewSummarizer()
 				result = summarizer.Summarize(content, summaryLength)
diff --git a/internal/handlers/translation/translation_handlers.go b/internal/handlers/translation/translation_handlers.go
index 7ba9e7be6..b66c23085 100644
--- a/internal/handlers/translation/translation_handlers.go
+++ b/internal/handlers/translation/translation_handlers.go
@@ -21,9 +21,10 @@ type TestCustomTranslationRequest struct {
 
 // TestCustomTranslationResponse represents the response from a custom translation test
 type TestCustomTranslationResponse struct {
-	Success bool   `json:"success"`
-	Result  string `json:"result,omitempty"`
-	Error   string `json:"error,omitempty"`
+	Success   bool   `json:"success"`
+	Result    string `json:"result,omitempty"`
+	Error     string `json:"error,omitempty"`
+	ErrorCode string `json:"error_code,omitempty"`
 }
 
 // HandleTranslateArticle translates an article's title.
@@ -270,7 +271,8 @@ func HandleTranslateText(h *core.Handler, w http.ResponseWriter, r *http.Request
 
 			// If AI fails, fallback to Google Translate
 			if err != nil {
-				log.Printf("AI translation failed, falling back to Google Translate: %v", err)
+				publicErr := ai.ClassifyUserFacingError(err)
+				log.Printf("AI translation failed code=%s status=%d; using Google Translate fallback", publicErr.Code, publicErr.HTTPStatus)
 				googleTranslator := translation.NewGoogleFreeTranslatorWithDB(h.DB)
 				translatedText, err = translation.TranslateMarkdownPreservingStructure(req.Text, googleTranslator, req.TargetLang)
 			}
@@ -412,7 +414,9 @@ func HandleTestCustomTranslation(h *core.Handler, w http.ResponseWriter, r *http
 	}
 
 	if err != nil {
-		resp["error"] = err.Error()
+		publicErr := ai.ClassifyUserFacingError(err)
+		resp["error"] = publicErr.Message
+		resp["error_code"] = publicErr.Code
 		w.WriteHeader(http.StatusBadRequest)
 	} else {
 		resp["translation"] = result