Add Voyage AI error handling improvements to Python and Java backends

- Python FastAPI backend:
  - Created custom exception classes (VoyageAuthError, VoyageAPIError)
  - Created error response utility function
  - Added global exception handlers in main.py
  - Updated vector search endpoint to use custom exceptions
  - Returns 400 for missing API key (SERVICE_UNAVAILABLE)
  - Returns 401 for invalid API key (VOYAGE_AUTH_ERROR)
  - Returns 503 for Voyage AI API errors (VOYAGE_API_ERROR)
  - Updated test to match new error handling behavior

- Java Spring backend:
  - Created custom exception classes (VoyageAuthException, VoyageAPIException, ServiceUnavailableException)
  - Updated GlobalExceptionHandler with handlers for new exceptions
  - Updated MovieServiceImpl to throw custom exceptions
  - Returns 400 for missing API key (SERVICE_UNAVAILABLE)
  - Returns 401 for invalid API key (VOYAGE_AUTH_ERROR)
  - Returns 503 for Voyage AI API errors (VOYAGE_API_ERROR)
  - Updated tests to expect ServiceUnavailableException instead of ValidationException

All three backends (Express, Python, Java) now have consistent Voyage AI error handling.

Author: cbullinger

mflix/server/java-spring/src/main/java/com/mongodb/samplemflix/exception/GlobalExceptionHandler.java

@@ -79,6 +79,61 @@ public ResponseEntity<ErrorResponse> handleMissingServletRequestParameter(
         return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
     }
 
+    @ExceptionHandler(ServiceUnavailableException.class)
+    public ResponseEntity<ErrorResponse> handleServiceUnavailableException(
+            ServiceUnavailableException ex, WebRequest request) {
+        logger.error("Service unavailable: {}", ex.getMessage());
+
+        ErrorResponse errorResponse = ErrorResponse.builder()
+                .success(false)
+                .message(ex.getMessage())
+                .error(ErrorResponse.ErrorDetails.builder()
+                        .message(ex.getMessage())
+                        .code("SERVICE_UNAVAILABLE")
+                        .build())
+                .timestamp(Instant.now().toString())
+                .build();
+
+        return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
+    }
+
+    @ExceptionHandler(VoyageAuthException.class)
+    public ResponseEntity<ErrorResponse> handleVoyageAuthException(
+            VoyageAuthException ex, WebRequest request) {
+        logger.error("Voyage AI authentication error: {}", ex.getMessage());
+
+        ErrorResponse errorResponse = ErrorResponse.builder()
+                .success(false)
+                .message(ex.getMessage())
+                .error(ErrorResponse.ErrorDetails.builder()
+                        .message(ex.getMessage())
+                        .code("VOYAGE_AUTH_ERROR")
+                        .details("Please verify your VOYAGE_API_KEY is correct in the .env file")
+                        .build())
+                .timestamp(Instant.now().toString())
+                .build();
+
+        return new ResponseEntity<>(errorResponse, HttpStatus.UNAUTHORIZED);
+    }
+
+    @ExceptionHandler(VoyageAPIException.class)
+    public ResponseEntity<ErrorResponse> handleVoyageAPIException(
+            VoyageAPIException ex, WebRequest request) {
+        logger.error("Voyage AI API error: {}", ex.getMessage());
+
+        ErrorResponse errorResponse = ErrorResponse.builder()
+                .success(false)
+                .message("Vector search service unavailable")
+                .error(ErrorResponse.ErrorDetails.builder()
+                        .message(ex.getMessage())
+                        .code("VOYAGE_API_ERROR")
+                        .build())
+                .timestamp(Instant.now().toString())
+                .build();
+
+        return new ResponseEntity<>(errorResponse, HttpStatus.SERVICE_UNAVAILABLE);
+    }
+
     @ExceptionHandler(DatabaseOperationException.class)
     public ResponseEntity<ErrorResponse> handleDatabaseOperationException(
             DatabaseOperationException ex, WebRequest request) {

mflix/server/java-spring/src/main/java/com/mongodb/samplemflix/exception/ServiceUnavailableException.java

@@ -0,0 +1,17 @@
+package com.mongodb.samplemflix.exception;
+
+/**
+ * Exception thrown when a required service is unavailable or not configured.
+ * 
+ * This exception results in a 400 Bad Request response with SERVICE_UNAVAILABLE code.
+ * Typically occurs when:
+ * - A required API key is not configured
+ * - A required service is not available
+ */
+public class ServiceUnavailableException extends RuntimeException {
+    
+    public ServiceUnavailableException(String message) {
+        super(message);
+    }
+}
+

mflix/server/java-spring/src/main/java/com/mongodb/samplemflix/exception/VoyageAPIException.java

@@ -0,0 +1,29 @@
+package com.mongodb.samplemflix.exception;
+
+/**
+ * Exception thrown when Voyage AI API returns an error.
+ * 
+ * This exception results in a 503 Service Unavailable response.
+ * Typically occurs when:
+ * - The Voyage AI API is down or unavailable
+ * - The API returns an error response
+ * - Network issues prevent communication with the API
+ */
+public class VoyageAPIException extends RuntimeException {
+    
+    private final int statusCode;
+    
+    public VoyageAPIException(String message, int statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+    
+    public VoyageAPIException(String message) {
+        this(message, 503);
+    }
+    
+    public int getStatusCode() {
+        return statusCode;
+    }
+}
+

mflix/server/java-spring/src/main/java/com/mongodb/samplemflix/exception/VoyageAuthException.java

@@ -0,0 +1,18 @@
+package com.mongodb.samplemflix.exception;
+
+/**
+ * Exception thrown when Voyage AI API authentication fails.
+ * 
+ * This exception results in a 401 Unauthorized response.
+ * Typically occurs when:
+ * - The API key is invalid
+ * - The API key is missing
+ * - The API key has expired
+ */
+public class VoyageAuthException extends RuntimeException {
+    
+    public VoyageAuthException(String message) {
+        super(message);
+    }
+}
+

mflix/server/java-spring/src/main/java/com/mongodb/samplemflix/service/MovieServiceImpl.java

@@ -6,7 +6,10 @@
 import com.mongodb.client.result.UpdateResult;
 import com.mongodb.samplemflix.exception.DatabaseOperationException;
 import com.mongodb.samplemflix.exception.ResourceNotFoundException;
+import com.mongodb.samplemflix.exception.ServiceUnavailableException;
 import com.mongodb.samplemflix.exception.ValidationException;
+import com.mongodb.samplemflix.exception.VoyageAPIException;
+import com.mongodb.samplemflix.exception.VoyageAuthException;
 import com.mongodb.samplemflix.model.Movie;
 import com.mongodb.samplemflix.model.dto.*;
 import com.mongodb.samplemflix.repository.MovieRepository;
@@ -821,8 +824,8 @@ public List<VectorSearchResult> vectorSearchMovies(String query, Integer limit)
         // Check if Voyage API key is configured
         if (voyageApiKey == null || voyageApiKey.trim().isEmpty() ||
             voyageApiKey.equals("your_voyage_api_key")) {
-            throw new ValidationException(
-                "Vector search unavailable: VOYAGE_API_KEY not configured. Please add your Voyage AI API key to the .env file"
+            throw new ServiceUnavailableException(
+                "Vector search unavailable: VOYAGE_API_KEY not configured. Please add your API key to the .env file"
             );
         }
 
@@ -929,10 +932,16 @@ public List<VectorSearchResult> vectorSearchMovies(String query, Integer limit)
 
             return results;
 
+        } catch (VoyageAuthException e) {
+            // Re-raise Voyage AI authentication errors to be handled by GlobalExceptionHandler
+            throw e;
+        } catch (VoyageAPIException e) {
+            // Re-raise Voyage AI API errors to be handled by GlobalExceptionHandler
+            throw e;
         } catch (IOException e) {
-            // Handle Voyage AI API errors
+            // Handle network errors calling Voyage AI API
             String errorMsg = e.getMessage() != null ? e.getMessage() : "Network error calling Voyage AI API";
-            throw new DatabaseOperationException("Error performing vector search: " + errorMsg);
+            throw new VoyageAPIException("Error performing vector search: " + errorMsg);
         } catch (InterruptedException e) {
             Thread.currentThread().interrupt();
             throw new DatabaseOperationException("Vector search was interrupted");
@@ -981,9 +990,12 @@ private List<Double> generateVoyageEmbedding(String text, String apiKey) throws
         if (response.statusCode() != 200) {
             // Handle authentication errors specifically
             if (response.statusCode() == 401) {
-                throw new IOException("Invalid Voyage AI API key. Please check your VOYAGE_API_KEY in the .env file");
+                throw new VoyageAuthException("Invalid Voyage AI API key. Please check your VOYAGE_API_KEY in the .env file");
             }
-            throw new IOException("Voyage AI API returned status code " + response.statusCode() + ": " + response.body());
+            throw new VoyageAPIException(
+                "Voyage AI API returned status code " + response.statusCode() + ": " + response.body(),
+                response.statusCode()
+            );
         }
 
         // Parse the JSON response to extract the embedding

mflix/server/java-spring/src/test/java/com/mongodb/samplemflix/service/MovieServiceTest.java

@@ -8,6 +8,7 @@
 import com.mongodb.client.MongoCollection;
 import com.mongodb.client.result.UpdateResult;
 import com.mongodb.samplemflix.exception.ResourceNotFoundException;
+import com.mongodb.samplemflix.exception.ServiceUnavailableException;
 import com.mongodb.samplemflix.exception.ValidationException;
 import com.mongodb.samplemflix.model.Movie;
 import com.mongodb.samplemflix.model.dto.BatchInsertResponse;
@@ -736,23 +737,23 @@ void testVectorSearchMovies_EmptyQuery() {
     }
 
     @Test
-    @DisplayName("Should throw ValidationException when API key is missing in vector search")
+    @DisplayName("Should throw ServiceUnavailableException when API key is missing in vector search")
     void testVectorSearchMovies_MissingApiKey() {
         // Arrange
         ReflectionTestUtils.setField(movieService, "voyageApiKey", null);
 
         // Act & Assert
-        assertThrows(ValidationException.class, () -> movieService.vectorSearchMovies("test query", 10));
+        assertThrows(ServiceUnavailableException.class, () -> movieService.vectorSearchMovies("test query", 10));
     }
 
     @Test
-    @DisplayName("Should throw ValidationException when API key is placeholder value in vector search")
+    @DisplayName("Should throw ServiceUnavailableException when API key is placeholder value in vector search")
     void testVectorSearchMovies_PlaceholderApiKey() {
         // Arrange
         ReflectionTestUtils.setField(movieService, "voyageApiKey", "your_voyage_api_key");
 
         // Act & Assert
-        assertThrows(ValidationException.class, () -> movieService.vectorSearchMovies("test query", 10));
+        assertThrows(ServiceUnavailableException.class, () -> movieService.vectorSearchMovies("test query", 10));
     }
 
     @Test

mflix/server/python-fastapi/.python-version

@@ -0,0 +1 @@
+3.13

mflix/server/python-fastapi/main.py

@@ -1,8 +1,11 @@
 from contextlib import asynccontextmanager
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
 from src.routers import movies
 from src.database.mongo_client import db, get_collection
+from src.utils.exceptions import VoyageAuthError, VoyageAPIError
+from src.utils.errorResponse import create_error_response
 
 import os
 from dotenv import load_dotenv
@@ -136,6 +139,31 @@ async def ensure_standard_index():
 
 app = FastAPI(lifespan=lifespan)
 
+# Add custom exception handlers
+@app.exception_handler(VoyageAuthError)
+async def voyage_auth_error_handler(request: Request, exc: VoyageAuthError):
+    """Handle Voyage AI authentication errors with 401 status."""
+    return JSONResponse(
+        status_code=401,
+        content=create_error_response(
+            message=exc.message,
+            code="VOYAGE_AUTH_ERROR",
+            details="Please verify your VOYAGE_API_KEY is correct in the .env file"
+        )
+    )
+
+@app.exception_handler(VoyageAPIError)
+async def voyage_api_error_handler(request: Request, exc: VoyageAPIError):
+    """Handle Voyage AI API errors with 503 status."""
+    return JSONResponse(
+        status_code=503,
+        content=create_error_response(
+            message="Vector search service unavailable",
+            code="VOYAGE_API_ERROR",
+            details=exc.message
+        )
+    )
+
 # Add CORS middleware
 cors_origins = os.getenv("CORS_ORIGINS", "http://localhost:3000,http://localhost:3001").split(",")
 app.add_middleware(

mflix/server/python-fastapi/src/routers/movies.py

@@ -1,12 +1,16 @@
 from fastapi import APIRouter, Query, Path, Body, HTTPException
+from fastapi.responses import JSONResponse
 from src.database.mongo_client import get_collection, voyage_ai_available
 from src.models.models import VectorSearchResult, CreateMovieRequest, Movie, SuccessResponse, UpdateMovieRequest, SearchMoviesResponse
 from typing import Any, List, Optional
 from src.utils.successResponse import create_success_response
+from src.utils.errorResponse import create_error_response
+from src.utils.exceptions import VoyageAuthError, VoyageAPIError
 from bson import ObjectId, errors
 import re
 from bson.errors import InvalidId
 import voyageai
+import os
 
 
 '''
@@ -316,11 +320,16 @@ async def vector_search_movies(
     Returns:
         SuccessResponse containing a list of movies with similarity scores
     """
+    # Check if Voyage AI API key is configured
     if not voyage_ai_available():
-        raise HTTPException(
-            status_code = 503,
-            detail="Vector search unavailable: VOYAGE_API_KEY not configured. Please add your API key to your .env file."
+        return JSONResponse(
+            status_code=400,
+            content=create_error_response(
+                message="Vector search unavailable: VOYAGE_API_KEY not configured. Please add your API key to the .env file",
+                code="SERVICE_UNAVAILABLE"
+            )
         )
+
     try:
         # Initialize the client here to avoid import-time errors
         vo = voyageai.Client()
@@ -390,10 +399,20 @@ async def vector_search_movies(
             f"Found {len(results)} similar movies for query: '{q}'"
         )
 
+    except VoyageAuthError:
+        # Re-raise custom exceptions to be handled by the exception handlers
+        raise
+    except VoyageAPIError:
+        # Re-raise custom exceptions to be handled by the exception handlers
+        raise
     except Exception as e:
+        # Log the error for debugging
+        print(f"Vector search error: {str(e)}")
+
+        # Handle generic errors
         raise HTTPException(
-            status_code = 500,
-            detail=f"An error occurred during vector search: {str(e)}"
+            status_code=500,
+            detail=f"Error performing vector search: {str(e)}"
         )
 
 """
@@ -1348,12 +1367,30 @@ def get_embedding(data, input_type = "document", client=None):
 
     Returns:
         Vector embeddings for the given input
+
+    Raises:
+        VoyageAuthError: If the API key is invalid (401)
+        VoyageAPIError: For other API errors
     """
     if client is None:
         client = voyageai.Client()
 
-    embeddings = client.embed(
-        data, model = model, output_dimension = outputDimension, input_type = input_type
-    ).embeddings
-    return embeddings[0]
+    try:
+        embeddings = client.embed(
+            data, model = model, output_dimension = outputDimension, input_type = input_type
+        ).embeddings
+        return embeddings[0]
+    except Exception as e:
+        error_message = str(e).lower()
+
+        # Check for authentication errors
+        if "401" in error_message or "unauthorized" in error_message or "invalid api key" in error_message:
+            raise VoyageAuthError("Invalid Voyage AI API key. Please check your VOYAGE_API_KEY in the .env file")
+
+        # Check for other API errors
+        if "api" in error_message or "voyage" in error_message:
+            raise VoyageAPIError(f"Voyage AI API error: {str(e)}", 503)
+
+        # Re-raise other exceptions
+        raise VoyageAPIError(f"Failed to generate embedding: {str(e)}", 500)