fix: surface DataForSEO auth failures as an actionable error instead of "unexpected error" (#53)

src/client/lib/error-messages.ts

@@ -22,6 +22,8 @@ const STANDARD_MESSAGES: Record<ErrorCode, string> = {
     "AI Optimization is not enabled for the connected DataForSEO account yet.",
   AI_SEARCH_BILLING_ISSUE:
     "The connected DataForSEO account has a billing or balance issue.",
+  DATAFORSEO_AUTH_FAILED:
+    "DataForSEO rejected the API key. Check that DATAFORSEO_API_KEY is the base64 of your DataForSEO login:password.",
   RATE_LIMITED: "Too many requests. Please wait and try again.",
   UPSTREAM_UNAVAILABLE:
     "The data provider is temporarily unavailable. Please retry in a moment.",

src/server/lib/dataforseo/core.ts

@@ -96,7 +96,9 @@ function createAuthenticatedFetch(classify?: DataforseoErrorClassifier) {
           ? "UPSTREAM_UNAVAILABLE"
           : response.status === 429
             ? "RATE_LIMITED"
-            : "INTERNAL_ERROR";
+            : response.status === 401
+              ? "DATAFORSEO_AUTH_FAILED"
+              : "INTERNAL_ERROR";
       const error = new AppError(
         code,
         `DataForSEO HTTP ${response.status} on ${path}`,

src/server/lib/dataforseoAccountState.ts

@@ -58,6 +58,14 @@ export async function fetchDataforseoAccountState(): Promise<DataforseoAccountSt
   });
 
   if (!response.ok) {
+    // 401/403 here means the API key itself is invalid or missing — surface a
+    // clear, actionable message instead of a generic "unexpected error".
+    if (response.status === 401 || response.status === 403) {
+      throw new AppError(
+        "DATAFORSEO_AUTH_FAILED",
+        `DataForSEO HTTP ${response.status} on /v3/appendix/user_data`,
+      );
+    }
     throw new AppError(
       "INTERNAL_ERROR",
       `DataForSEO HTTP ${response.status} on /v3/appendix/user_data`,

src/shared/error-codes.ts

@@ -14,6 +14,7 @@ const ERROR_CODES = [
   "BACKLINKS_BILLING_ISSUE",
   "AI_SEARCH_NOT_ENABLED",
   "AI_SEARCH_BILLING_ISSUE",
+  "DATAFORSEO_AUTH_FAILED",
   "RATE_LIMITED",
   "UPSTREAM_UNAVAILABLE",
   "CONFLICT",