From b8a4057565cb430e0697304015b830fa790800c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=A7=91=E6=9E=97=20KELIN?=
 <167663109+HuangYuChuh@users.noreply.github.com>
Date: Mon, 13 Apr 2026 08:03:42 +0800
Subject: [PATCH] feat: add human-readable hints for API check failures (#17)

---
 nodes/api_routes.py        | 21 ++++++++++++++++++++-
 web/js/provider_manager.js |  9 +++++++--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/nodes/api_routes.py b/nodes/api_routes.py
index fe9dab3..49a3d74 100644
--- a/nodes/api_routes.py
+++ b/nodes/api_routes.py
@@ -261,9 +261,28 @@ async def check_provider(request: web.Request) -> web.Response:
         })
 
     except Exception as e:
+        error_msg = str(e)[:500]
+        hint = ""
+        error_lower = error_msg.lower()
+        if "401" in error_msg or "unauthorized" in error_lower or "authentication" in error_lower:
+            hint = "API Key may be invalid or expired. Please check and re-enter."
+        elif "403" in error_msg or "forbidden" in error_lower:
+            hint = "Access denied. Your API Key may lack required permissions."
+        elif "404" in error_msg or "not found" in error_lower:
+            hint = "Model or endpoint not found. Please verify the model name and Base URL."
+        elif "429" in error_msg or "rate" in error_lower or "quota" in error_lower:
+            hint = "Rate limited or quota exceeded. Check your usage on the provider's website."
+        elif "timeout" in error_lower or "timed out" in error_lower:
+            hint = "Connection timed out. Check your network or try again later."
+        elif "ssl" in error_lower or "certificate" in error_lower:
+            hint = "SSL certificate error. Try enabling 'Skip SSL Verification' for this provider."
+        elif "connection" in error_lower or "refused" in error_lower or "resolve" in error_lower:
+            hint = "Cannot connect to the server. Please check the Base URL and your network."
+
         return web.json_response({
             "status": "error",
-            "message": str(e)[:500]
+            "message": error_msg,
+            "hint": hint
         }, status=502)
 
 
diff --git a/web/js/provider_manager.js b/web/js/provider_manager.js
index b8a9396..e132a32 100644
--- a/web/js/provider_manager.js
+++ b/web/js/provider_manager.js
@@ -36,6 +36,7 @@ const I18N_DICT = {
         connected: "Connected!",
         failed: "Failed",
         conn_failed: "Connection Failed",
+        error_detail: "Technical detail",
         network_err_title: "⚠️ Network Error",
         network_err_msg: "❌ Request failed. Network error or CORS issue.",
         search_placeholder: "Search providers/models...",
@@ -103,6 +104,7 @@ const I18N_DICT = {
         connected: "连通成功！",
         failed: "连接失败",
         conn_failed: "连接失败",
+        error_detail: "技术详情",
         network_err_title: "⚠️ 网络错误",
         network_err_msg: "❌ 请求失败。网络错误或存在跨域(CORS)限制。",
         search_placeholder: "搜索 供应商/模型...",
@@ -404,8 +406,11 @@ class ProviderManager {
                 btn.style.boxShadow = "0 0 12px rgba(248, 113, 113, 0.3)";
                 console.warn("[LLMs Toolkit] Connect Error: ", data.message);
 
-                // Still show the alert for the specific error message
-                setTimeout(() => this.showAlert(t("conn_failed"), "❌ " + data.message), 100);
+                // Show user-friendly hint (if available) with raw error as detail
+                const alertMsg = data.hint
+                    ? `${data.hint}\n\n${t("error_detail")}: ${data.message}`
+                    : `❌ ${data.message}`;
+                setTimeout(() => this.showAlert(t("conn_failed"), alertMsg), 100);
             }
         } catch (e) {
             console.error(e);