Add error handling for missing/invalid Voyage API key

- Add custom error classes (VoyageAuthError, VoyageAPIError) to distinguish error types
- Update generateVoyageEmbedding to throw VoyageAuthError for 401 responses
- Return 401 status for authentication errors, 503 for API errors
- Improve client-side error handling with user-friendly messages
- Update tests to verify proper error handling for different scenarios

Author: cbullinger

mflix/client/app/aggregations/page.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
-import { fetchMoviesWithComments, fetchMoviesByYear, fetchDirectorStats } from '../lib/api';
-import { MovieWithComments, YearlyStats, DirectorStats } from '../types/aggregations';
+import { fetchMoviesWithComments, fetchMoviesByYear, fetchDirectorStats } from '@/lib/api';
+import { MovieWithComments, YearlyStats, DirectorStats } from '@/types/aggregations';
 import styles from './aggregations.module.css';
 
 export default async function AggregationsPage() {

mflix/client/app/lib/api.ts

@@ -680,16 +680,36 @@ export async function vectorSearchMovies(searchParams: {
     const result = await response.json();
 
     if (!response.ok) {
-      return { 
-        success: false, 
-        error: result.error || `Failed to perform vector search: ${response.status}` 
+      // Extract error message from the standardized error response
+      const errorMessage = result.message || result.error?.message || `Failed to perform vector search: ${response.status}`;
+      const errorCode = result.error?.code;
+
+      // Provide user-friendly messages for specific error codes
+      if (errorCode === 'VOYAGE_AUTH_ERROR') {
+        return {
+          success: false,
+          error: 'Vector search unavailable: Your Voyage AI API key is missing or invalid. Please add a valid VOYAGE_API_KEY to your .env file and restart the server.'
+        };
+      }
+
+      if (errorCode === 'SERVICE_UNAVAILABLE' || errorCode === 'VOYAGE_API_ERROR') {
+        return {
+          success: false,
+          error: errorMessage || 'Vector search service is currently unavailable. Please try again later.'
+        };
+      }
+
+      return {
+        success: false,
+        error: errorMessage
       };
     }
 
     if (!result.success) {
-      return { 
-        success: false, 
-        error: result.error || 'API returned error response' 
+      const errorMessage = result.message || result.error?.message || 'API returned error response';
+      return {
+        success: false,
+        error: errorMessage
       };
     }
 

mflix/client/app/movie/[id]/error.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect } from 'react';
 import Link from 'next/link';
-import { ROUTES } from '../../lib/constants';
+import { ROUTES } from '@/lib/constants';
 import styles from './error.module.css';
 
 export default function MovieDetailsError({

mflix/client/app/movie/[id]/loading.tsx

@@ -1,5 +1,5 @@
 import pageStyles from './page.module.css';
-import { MovieDetailsSkeleton } from '../../components/LoadingSkeleton';
+import { MovieDetailsSkeleton } from '@/components';
 
 export default function MovieDetailsLoading() {
   return (

mflix/server/js-express/src/controllers/movieController.ts

@@ -835,6 +835,36 @@ export async function vectorSearchMovies(req: Request, res: Response): Promise<v
     );
   } catch (error) {
     console.error("Vector search error:", error);
+
+    // Handle Voyage AI authentication errors
+    if (error instanceof VoyageAuthError) {
+      res
+        .status(401)
+        .json(
+          createErrorResponse(
+            error.message,
+            "VOYAGE_AUTH_ERROR",
+            "Please verify your VOYAGE_API_KEY is correct in the .env file"
+          )
+        );
+      return;
+    }
+
+    // Handle other Voyage AI API errors
+    if (error instanceof VoyageAPIError) {
+      res
+        .status(503)
+        .json(
+          createErrorResponse(
+            "Vector search service unavailable",
+            "VOYAGE_API_ERROR",
+            error.message
+          )
+        );
+      return;
+    }
+
+    // Handle generic errors
     res
       .status(500)
       .json(
@@ -1160,16 +1190,41 @@ export async function getDirectorsWithMostMovies(
   );
 }
 
+/**
+ * Custom error class for Voyage AI API authentication errors
+ */
+class VoyageAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "VoyageAuthError";
+  }
+}
+
+/**
+ * Custom error class for Voyage AI API errors
+ */
+class VoyageAPIError extends Error {
+  public statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "VoyageAPIError";
+    this.statusCode = statusCode;
+  }
+}
+
 /**
  * Generates a vector embedding using the Voyage AI REST API.
- * 
+ *
  * This function calls the Voyage AI API directly to generate embeddings with 2048 dimensions.
  * The voyage-3-large model supports multiple dimensions (256, 512, 1024, 2048), and we explicitly
  * request 2048 to match the vector search index configuration.
- * 
+ *
  * @param text The text to generate an embedding for
  * @param apiKey The Voyage AI API key
  * @returns Promise<number[]> representing the embedding vector
+ * @throws VoyageAuthError if the API key is invalid (401)
+ * @throws VoyageAPIError for other API errors
  */
 async function generateVoyageEmbedding(text: string, apiKey: string): Promise<number[]> {
   // Build the request body with output_dimension set to 2048
@@ -1192,21 +1247,36 @@ async function generateVoyageEmbedding(text: string, apiKey: string): Promise<nu
 
     if (!response.ok) {
       const errorText = await response.text();
-      throw new Error(`Voyage AI API returned status ${response.status}: ${errorText}`);
+
+      // Handle authentication errors specifically
+      if (response.status === 401) {
+        throw new VoyageAuthError("Invalid Voyage AI API key. Please check your VOYAGE_API_KEY in the .env file");
+      }
+
+      throw new VoyageAPIError(
+        `Voyage AI API returned status ${response.status}: ${errorText}`,
+        response.status
+      );
     }
 
     const data = await response.json() as VoyageAIResponse;
-    
+
     // Extract the embedding from the response
     if (!data.data || !data.data[0] || !data.data[0].embedding) {
-      throw new Error("Invalid response format from Voyage AI API");
+      throw new VoyageAPIError("Invalid response format from Voyage AI API", 500);
     }
 
     return data.data[0].embedding;
   } catch (error) {
+    // Re-throw our custom errors
+    if (error instanceof VoyageAuthError || error instanceof VoyageAPIError) {
+      throw error;
+    }
+
+    // Wrap other errors
     if (error instanceof Error) {
-      throw new Error(`Failed to generate embedding: ${error.message}`);
+      throw new VoyageAPIError(`Failed to generate embedding: ${error.message}`, 500);
     }
-    throw new Error("Failed to generate embedding: Unknown error");
+    throw new VoyageAPIError("Failed to generate embedding: Unknown error", 500);
   }
 }

mflix/server/js-express/tests/controllers/movieController.test.ts

@@ -880,7 +880,7 @@ describe("Movie Controller Tests", () => {
       );
     });
 
-    it("should handle Voyage AI API errors", async () => {
+    it("should handle Voyage AI authentication errors with 401 status", async () => {
       mockFetch.mockResolvedValueOnce({
         ok: false,
         status: 401,
@@ -891,11 +891,30 @@ describe("Movie Controller Tests", () => {
 
       await vectorSearchMovies(mockRequest as Request, mockResponse as Response);
 
-      expect(mockStatus).toHaveBeenCalledWith(500);
+      expect(mockStatus).toHaveBeenCalledWith(401);
       expect(mockCreateErrorResponse).toHaveBeenCalledWith(
-        "Error performing vector search",
-        "VECTOR_SEARCH_ERROR",
-        expect.stringContaining("Voyage AI API returned status 401")
+        "Invalid Voyage AI API key. Please check your VOYAGE_API_KEY in the .env file",
+        "VOYAGE_AUTH_ERROR",
+        "Please verify your VOYAGE_API_KEY is correct in the .env file"
+      );
+    });
+
+    it("should handle other Voyage AI API errors with 503 status", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        text: () => Promise.resolve("Internal Server Error"),
+      } as any);
+
+      mockRequest.query = { q: "test" };
+
+      await vectorSearchMovies(mockRequest as Request, mockResponse as Response);
+
+      expect(mockStatus).toHaveBeenCalledWith(503);
+      expect(mockCreateErrorResponse).toHaveBeenCalledWith(
+        "Vector search service unavailable",
+        "VOYAGE_API_ERROR",
+        expect.stringContaining("Voyage AI API returned status 500")
       );
     });