refactor(errors): normalize user-facing error messages

src/core/errors/__tests__/exception-handler.test.ts

@@ -96,9 +96,23 @@ describe("ExceptionHandler", () => {
       message: "plain failure",
     });
 
+    expect(ExceptionHandler.handle({ message: "card declined" })).toEqual({
+      code: ExceptionCode.unknown,
+      message: "card declined",
+    });
+
     expect(ExceptionHandler.handle({ nope: true })).toEqual({
       code: ExceptionCode.unknown,
       message: "Something went wrong. Please try again.",
     });
   });
+
+  it("uses call-site fallback text only for unrecognized errors", () => {
+    expect(ExceptionHandler.message({ nope: true }, "Domain fallback")).toBe(
+      "Domain fallback",
+    );
+    expect(ExceptionHandler.message(new Error("specific"), "Domain fallback")).toBe(
+      "specific",
+    );
+  });
 });

src/core/errors/exception-handler.ts

@@ -1,7 +1,11 @@
 import { AppException } from "./app-exception";
+import { ExceptionCode } from "./exception-code";
 import type { ExceptionResult } from "./exception-result";
 import { ApiExceptionHandler } from "./handlers/api-exception-handler";
-import { FallbackExceptionHandler } from "./handlers/fallback-exception-handler";
+import {
+  DEFAULT_EXCEPTION_MESSAGE,
+  FallbackExceptionHandler,
+} from "./handlers/fallback-exception-handler";
 import { NetworkExceptionHandler } from "./handlers/network-exception-handler";
 import { PaymentExceptionHandler } from "./handlers/payment-exception-handler";
 import { StorageExceptionHandler } from "./handlers/storage-exception-handler";
@@ -36,8 +40,16 @@ export class ExceptionHandler {
     return FallbackExceptionHandler.handle(error);
   }
 
-  static message(error: unknown): string {
-    return ExceptionHandler.handle(error).message;
+  static message(error: unknown, fallbackMessage?: string): string {
+    const result = ExceptionHandler.handle(error);
+    if (
+      fallbackMessage &&
+      result.code === ExceptionCode.unknown &&
+      result.message === DEFAULT_EXCEPTION_MESSAGE
+    ) {
+      return fallbackMessage;
+    }
+    return result.message;
   }
 
   static toError(error: unknown): AppException {

src/core/errors/handlers/fallback-exception-handler.ts

@@ -1,6 +1,9 @@
 import { ExceptionCode } from "../exception-code";
 import type { ExceptionResult } from "../exception-result";
 
+export const DEFAULT_EXCEPTION_MESSAGE =
+  "Something went wrong. Please try again.";
+
 export class FallbackExceptionHandler {
   static handle(error: unknown): ExceptionResult {
     return {
@@ -19,5 +22,18 @@ function resolveMessage(error: unknown): string {
     return error;
   }
 
-  return "Something went wrong. Please try again.";
+  if (isMessageLike(error) && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return DEFAULT_EXCEPTION_MESSAGE;
+}
+
+function isMessageLike(error: unknown): error is { message: string } {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof error.message === "string"
+  );
 }

src/core/net/chat-websocket.ts

@@ -9,6 +9,7 @@
  *   - onError(errorMessage)
  */
 import { getApiConfig } from "@/core/net/config/api_config";
+import { ExceptionHandler } from "@/core/errors";
 import { AppEnvUtil, Logger } from "@/utils";
 
 const log = new Logger("ChatWebSocket");
@@ -89,7 +90,9 @@ export class ChatWebSocket {
       };
     } catch (e) {
       logWebSocketError("✕ WS CONNECT FAILED", e);
-      this.onError?.(e instanceof Error ? e.message : String(e));
+      this.onError?.(
+        ExceptionHandler.message(e, "WebSocket connection failed."),
+      );
     }
   }