feat: actionable error messages — overhaul friendlyCalcomError, consolidate CalcomApiError handling via deps

Author: dhairyashiil

apps/chat/lib/bot.ts

@@ -426,24 +426,34 @@ function isSlackAuthError(err: unknown): boolean {
   return false;
 }
 
-function friendlyCalcomError(err: CalcomApiError): string {
+function friendlyCalcomError(err: CalcomApiError, context?: string): string {
+  const apiDetail = err.message && !err.message.startsWith("Cal.com API error:")
+    ? ` (${err.message})`
+    : "";
+
   switch (err.statusCode) {
     case 400:
-    case 422:
-      return "The request was invalid. Please check the details and try again.";
+      return `The request had invalid data${apiDetail}. Please check the details and try again.`;
     case 401:
     case 403:
-      return "Your Cal.com session has expired. Please reconnect your account.";
+      return "Your Cal.com session has expired. Please reconnect your account to continue.";
     case 404:
-      return "The booking or event type was not found.";
+      return `The requested resource was not found${apiDetail}. It may have been deleted or the ID is incorrect.`;
     case 409:
-      return "This time slot is no longer available.";
+      return context === "booking"
+        ? "This time slot is no longer available \u2014 someone else may have just booked it. Would you like me to check for other available times?"
+        : `There was a conflict${apiDetail}. The resource may have been modified. Please try again.`;
+    case 422:
+      return `The request was missing required information${apiDetail}. Please provide all required fields and try again.`;
     case 429:
-      return "Cal.com rate limit reached. Please try again in a moment.";
+      return "Cal.com's rate limit has been reached. Please wait about 30 seconds and try again.";
     default:
-      return err.statusCode && err.statusCode >= 500
-        ? "Cal.com is experiencing issues. Please try again later."
-        : "Something went wrong with the Cal.com API. Please try again.";
+      if (err.statusCode && err.statusCode >= 500) {
+        return err.code === "FETCH_RETRY_EXHAUSTED"
+          ? "Cal.com is not responding after multiple attempts. The service may be temporarily down \u2014 please try again in a few minutes."
+          : "Cal.com is experiencing issues right now. Please try again in a moment.";
+      }
+      return `Something went wrong with the Cal.com API${apiDetail}. Please try again.`;
   }
 }
 
@@ -1126,4 +1136,5 @@ registerSlackHandlers(bot, getSlackAdapter, {
   extractTeamIdFromRaw,
   buildHistory,
   makeLookupSlackUser,
+  friendlyCalcomError,
 });

apps/chat/lib/handlers/slack.ts

@@ -90,6 +90,7 @@ export interface RegisterSlackHandlersDeps {
   extractTeamIdFromRaw: (raw: unknown, adapterName?: string) => string;
   buildHistory: (thread: Thread) => Promise<ModelMessage[]>;
   makeLookupSlackUser: (teamId: string) => LookupPlatformUserFn;
+  friendlyCalcomError: (err: import("../calcom/client").CalcomApiError, context?: string) => string;
 }
 
 function oauthLinkMessage(platform: string, teamId: string, userId: string) {
@@ -119,6 +120,7 @@ export function registerSlackHandlers(
     extractTeamIdFromRaw,
     buildHistory,
     makeLookupSlackUser,
+    friendlyCalcomError,
   } = deps;
 
   async function safeChannelPost(
@@ -583,7 +585,7 @@ export function registerSlackHandlers(
           if (isAIToolCallError(lastStreamErrorRef.current))
             return "I had trouble processing that request. Please try again, or be more specific (e.g. run /cal bookings first, then cancel by booking ID).";
           if (lastStreamErrorRef.current instanceof CalcomApiError)
-            return `The request failed: ${lastStreamErrorRef.current.statusCode === 401 || lastStreamErrorRef.current.statusCode === 403 ? "Your Cal.com session has expired. Please reconnect your account." : lastStreamErrorRef.current.statusCode === 429 ? "Cal.com rate limit reached. Please try again in a moment." : "Something went wrong with the Cal.com API. Please try again."}`;
+            return friendlyCalcomError(lastStreamErrorRef.current);
           if (isSlackAuthError(err))
             return "Sorry, something went wrong while processing your request. Please try again.";
           return undefined;
@@ -940,9 +942,7 @@ export function registerSlackHandlers(
         logContext: "confirm_booking",
         getCustomErrorMessage: (err) => {
           if (err instanceof CalcomApiError) {
-            if (err.statusCode === 409) return "This time slot is no longer available. Please pick another.";
-            if (err.statusCode === 422) return "The booking details are incomplete. Please try again.";
-            return "Failed to create the booking. Please try again.";
+            return friendlyCalcomError(err, "booking");
           }
           return err instanceof Error ? "Failed to create the booking. Please try again." : undefined;
         },
@@ -1005,7 +1005,7 @@ export function registerSlackHandlers(
           if (isAIToolCallError(lastStreamErrorRef.current))
             return "I had trouble processing that request. Please try again, or be more specific (e.g. run /cal bookings first, then cancel by booking ID).";
           if (lastStreamErrorRef.current instanceof CalcomApiError)
-            return `The request failed: ${lastStreamErrorRef.current.statusCode === 401 || lastStreamErrorRef.current.statusCode === 403 ? "Your Cal.com session has expired. Please reconnect your account." : lastStreamErrorRef.current.statusCode === 429 ? "Cal.com rate limit reached. Please try again in a moment." : "Something went wrong with the Cal.com API. Please try again."}`;
+            return friendlyCalcomError(lastStreamErrorRef.current);
           if (isSlackAuthError(err))
             return "Sorry, something went wrong while processing your request. Please try again.";
           return undefined;