feat: Implemented consistent error handling

ntkathole · ntkathole · commit 7f10151f1543 · 2025-08-11T19:14:56.000+05:30
Signed-off-by: ntkathole &lt;nikhilkathole2683@gmail.com&gt;
diff --git a/docs/reference/feature-servers/registry-server.md b/docs/reference/feature-servers/registry-server.md
@@ -801,6 +801,36 @@ All endpoints return JSON responses with the following general structure:
 - **Not Found (404)**: Requested resource does not exist
 - **Internal Server Error (500)**: Server-side error
 
+### Error Handling
+
+The REST API provides consistent error responses with HTTP status codes included in the JSON response body. All error responses follow this format:
+
+```json
+{
+  "status_code": 404,
+  "detail": "Entity 'user_id' does not exist in project 'demo_project'",
+  "error_type": "FeastObjectNotFoundException"
+}
+```
+
+#### Error Response Fields
+
+- **`status_code`**: The HTTP status code (e.g., 404, 422, 500)
+- **`detail`**: Human-readable error message describing the issue
+- **`error_type`**: The specific type of error that occurred
+
+#### HTTP Status Code Mapping
+
+| HTTP Status | Error Type | Description | Common Causes |
+|-------------|------------|-------------|---------------|
+| **400** | `HTTPException` | Bad Request | Invalid request format or parameters |
+| **401** | `HTTPException` | Unauthorized | Missing or invalid authentication token |
+| **403** | `FeastPermissionError` | Forbidden | Insufficient permissions to access the resource |
+| **404** | `FeastObjectNotFoundException` | Not Found | Requested entity, feature view, data source, etc. does not exist |
+| **422** | `ValidationError` / `RequestValidationError` / `ValueError` / `PushSourceNotFoundException` | Unprocessable Entity | Validation errors, missing required parameters, or invalid input |
+| **500** | `InternalServerError` | Internal Server Error | Unexpected server-side errors |
+
+
 #### Enhanced Response Formats
 
 The REST API now supports enhanced response formats for relationships and pagination:
diff --git a/sdk/python/feast/api/registry/rest/features.py b/sdk/python/feast/api/registry/rest/features.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, Query
 
 from feast.api.registry.rest.codegen_utils import render_feature_code
 from feast.api.registry.rest.rest_utils import (
@@ -70,52 +70,35 @@ def get_feature(
             name=name,
         )
 
-        try:
-            try:
-                response = grpc_call(grpc_handler.GetFeature, req)
-            except Exception as e:
-                raise HTTPException(
-                    status_code=404,
-                    detail=f"Feature '{name}' not found in feature view '{feature_view}' in project '{project}'",
-                ) from e
+        response = grpc_call(grpc_handler.GetFeature, req)
 
-            if include_relationships:
-                response["relationships"] = get_object_relationships(
-                    grpc_handler, "feature", name, project
-                )
-
-            if response:
-                dtype_str = response.get("type") or response.get("dtype")
-                value_type_enum = (
-                    _convert_value_type_str_to_value_type(dtype_str.upper())
-                    if dtype_str
-                    else None
-                )
-                feast_type = (
-                    from_value_type(value_type_enum) if value_type_enum else None
-                )
-                dtype = (
-                    feast_type.__name__
-                    if feast_type and hasattr(feast_type, "__name__")
-                    else "String"
-                )
-                context = dict(
-                    name=response.get("name", name),
-                    dtype=dtype,
-                    description=response.get("description", ""),
-                    tags=response.get("tags", response.get("labels", {})) or {},
-                )
-                response["featureDefinition"] = render_feature_code(context)
-
-            return response
+        if include_relationships:
+            response["relationships"] = get_object_relationships(
+                grpc_handler, "feature", name, project
+            )
 
-        except HTTPException:
-            raise
-        except Exception as e:
-            raise HTTPException(
-                status_code=500,
-                detail=f"Internal server error while retrieving feature '{name}' from feature view '{feature_view}' in project '{project}': {str(e)}",
+        if response:
+            dtype_str = response.get("type") or response.get("dtype")
+            value_type_enum = (
+                _convert_value_type_str_to_value_type(dtype_str.upper())
+                if dtype_str
+                else None
             )
+            feast_type = from_value_type(value_type_enum) if value_type_enum else None
+            dtype = (
+                feast_type.__name__
+                if feast_type and hasattr(feast_type, "__name__")
+                else "String"
+            )
+            context = dict(
+                name=response.get("name", name),
+                dtype=dtype,
+                description=response.get("description", ""),
+                tags=response.get("tags", response.get("labels", {})) or {},
+            )
+            response["featureDefinition"] = render_feature_code(context)
+
+        return response
 
     @router.get("/features/all")
     def list_features_all(
diff --git a/sdk/python/feast/api/registry/rest/lineage.py b/sdk/python/feast/api/registry/rest/lineage.py
@@ -2,7 +2,7 @@
 
 from typing import Optional
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, Query
 
 from feast.api.registry.rest.rest_utils import (
     create_grpc_pagination_params,
@@ -84,9 +84,8 @@ def get_object_relationships_path(
             "feature",
         ]
         if object_type not in valid_types:
-            raise HTTPException(
-                status_code=400,
-                detail=f"Invalid object_type. Must be one of: {', '.join(valid_types)}",
+            raise ValueError(
+                f"Invalid object_type. Must be one of: {', '.join(valid_types)}"
             )
 
         req = RegistryServer_pb2.GetObjectRelationshipsRequest(
diff --git a/sdk/python/feast/api/registry/rest/rest_registry_server.py b/sdk/python/feast/api/registry/rest/rest_registry_server.py
@@ -2,10 +2,18 @@
 import logging
 import re
 
-from fastapi import Depends, FastAPI, status
+from fastapi import Depends, FastAPI, HTTPException, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError
 
 from feast import FeatureStore
 from feast.api.registry.rest import register_all_routes
+from feast.errors import (
+    FeastObjectNotFoundException,
+    FeastPermissionError,
+    PushSourceNotFoundException,
+)
 from feast.permissions.auth.auth_manager import get_auth_manager
 from feast.permissions.server.rest import inject_user_details
 from feast.permissions.server.utils import (
@@ -62,11 +70,113 @@ def __init__(self, store: FeatureStore):
                 "X-Frame-Options": "DENY",
             },
         )
+        self._add_exception_handlers()
         self._add_logging_middleware()
         self._add_openapi_security()
         self._init_auth()
         self._register_routes()
 
+    def _add_exception_handlers(self):
+        """Add custom exception handlers to include HTTP status codes in JSON responses."""
+
+        @self.app.exception_handler(HTTPException)
+        async def http_exception_handler(request: Request, exc: HTTPException):
+            return JSONResponse(
+                status_code=exc.status_code,
+                content={
+                    "status_code": exc.status_code,
+                    "detail": exc.detail,
+                    "error_type": "HTTPException",
+                },
+            )
+
+        @self.app.exception_handler(FeastObjectNotFoundException)
+        async def feast_object_not_found_handler(
+            request: Request, exc: FeastObjectNotFoundException
+        ):
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "status_code": 404,
+                    "detail": str(exc),
+                    "error_type": "FeastObjectNotFoundException",
+                },
+            )
+
+        @self.app.exception_handler(FeastPermissionError)
+        async def feast_permission_error_handler(
+            request: Request, exc: FeastPermissionError
+        ):
+            return JSONResponse(
+                status_code=403,
+                content={
+                    "status_code": 403,
+                    "detail": str(exc),
+                    "error_type": "FeastPermissionError",
+                },
+            )
+
+        @self.app.exception_handler(PushSourceNotFoundException)
+        async def push_source_not_found_handler(
+            request: Request, exc: PushSourceNotFoundException
+        ):
+            return JSONResponse(
+                status_code=422,
+                content={
+                    "status_code": 422,
+                    "detail": str(exc),
+                    "error_type": "PushSourceNotFoundException",
+                },
+            )
+
+        @self.app.exception_handler(ValidationError)
+        async def validation_error_handler(request: Request, exc: ValidationError):
+            return JSONResponse(
+                status_code=422,
+                content={
+                    "status_code": 422,
+                    "detail": str(exc),
+                    "error_type": "ValidationError",
+                },
+            )
+
+        @self.app.exception_handler(RequestValidationError)
+        async def request_validation_error_handler(
+            request: Request, exc: RequestValidationError
+        ):
+            return JSONResponse(
+                status_code=422,
+                content={
+                    "status_code": 422,
+                    "detail": str(exc),
+                    "error_type": "RequestValidationError",
+                },
+            )
+
+        @self.app.exception_handler(ValueError)
+        async def value_error_handler(request: Request, exc: ValueError):
+            return JSONResponse(
+                status_code=422,
+                content={
+                    "status_code": 422,
+                    "detail": str(exc),
+                    "error_type": "ValueError",
+                },
+            )
+
+        @self.app.exception_handler(Exception)
+        async def generic_exception_handler(request: Request, exc: Exception):
+            logger.error(f"Unhandled exception: {exc}", exc_info=True)
+
+            return JSONResponse(
+                status_code=500,
+                content={
+                    "status_code": 500,
+                    "detail": f"Internal server error: {str(exc)}",
+                    "error_type": "InternalServerError",
+                },
+            )
+
     def _add_logging_middleware(self):
         from fastapi import Request
         from starlette.middleware.base import BaseHTTPMiddleware
diff --git a/sdk/python/feast/api/registry/rest/rest_utils.py b/sdk/python/feast/api/registry/rest/rest_utils.py
@@ -1,9 +1,13 @@
 from typing import Callable, Dict, List, Optional
 
-from fastapi import HTTPException, Query
+from fastapi import Query
 from google.protobuf.json_format import MessageToDict
 
-from feast.errors import FeastObjectNotFoundException
+from feast.errors import (
+    FeastObjectNotFoundException,
+    FeastPermissionError,
+    PushSourceNotFoundException,
+)
 from feast.protos.feast.registry import RegistryServer_pb2
 
 
@@ -14,10 +18,14 @@ def grpc_call(handler_fn, request):
     try:
         response = handler_fn(request, context=None)
         return MessageToDict(response)
-    except FeastObjectNotFoundException as e:
-        raise HTTPException(status_code=404, detail=str(e))
-    except Exception:
-        raise HTTPException(status_code=500, detail="Internal server error")
+    except (
+        FeastObjectNotFoundException,
+        FeastPermissionError,
+        PushSourceNotFoundException,
+    ):
+        raise
+    except Exception as e:
+        raise e
 
 
 def get_object_relationships(
diff --git a/sdk/python/feast/registry_server.py b/sdk/python/feast/registry_server.py
@@ -12,7 +12,7 @@
 from feast.base_feature_view import BaseFeatureView
 from feast.data_source import DataSource
 from feast.entity import Entity
-from feast.errors import FeatureViewNotFoundException
+from feast.errors import FeastObjectNotFoundException, FeatureViewNotFoundException
 from feast.feast_object import FeastObject
 from feast.feature_view import FeatureView
 from feast.grpc_error_interceptor import ErrorInterceptor
@@ -1205,9 +1205,9 @@ def GetFeature(self, request: RegistryServer_pb2.GetFeatureRequest, context):
                         last_updated_timestamp=last_updated_timestamp,
                         tags=getattr(feature, "tags", {}),
                     )
-        context.set_code(grpc.StatusCode.NOT_FOUND)
-        context.set_details("Feature not found")
-        return Feature()
+        raise FeastObjectNotFoundException(
+            f"Feature {request.name} not found in feature view {request.feature_view} in project {request.project}"
+        )
 
 
 def start_server(
diff --git a/sdk/python/tests/unit/api/test_api_rest_registry.py b/sdk/python/tests/unit/api/test_api_rest_registry.py
