day #48 fastapi #5 http status code & error handling

Author: stackjay

workspace/7_framework/fastapi/README.md

@@ -81,6 +81,10 @@ uvicorn main:app --reload
   Learn how to handle JSON request bodies, work with form data and file uploads, and combine different types of parameters in your API endpoints.
   _Includes: request body examples, form and file upload handling, mixed parameter endpoints, and test coverage._
 
+- [Day 05: HTTP Status Codes and Error Handling](day05/README.md)
+  Learn how to use and return appropriate HTTP status codes, create custom exception classes, handle validation and business logic errors, and implement global exception handlers for consistent error responses.
+  _Includes: custom error classes, exception handlers, validation and business logic error handling, logging, and test coverage._
+
 ---
 
 ## Recommended Project Structure

workspace/7_framework/fastapi/day05/README.md

@@ -0,0 +1,106 @@
+# FastAPI Day 05: HTTP Status Codes and Error Handling
+
+Welcome to **Day 05** of the FastAPI tutorial! Today you'll learn how to handle HTTP status codes, create custom error responses, and manage exceptions in your API endpoints.
+
+---
+
+## What You'll Learn
+
+- How to use and return appropriate HTTP status codes
+- How to create and use custom exception classes
+- How to handle validation and business logic errors gracefully
+- How to implement global exception handlers for consistent error responses
+- How to write automated tests for error handling
+
+---
+
+## Key Concepts
+
+### 1. HTTP Status Codes
+
+- **HTTP status codes** communicate the result of an API request.
+- Use codes like `200 OK`, `201 Created`, `404 Not Found`, `409 Conflict`, `422 Unprocessable Entity`, and `500 Internal Server Error` to indicate different outcomes.
+
+Example status codes:
+```
+201 Created - When a new item or order is successfully created
+404 Not Found - When a requested resource does not exist
+409 Conflict - When there is a duplicate or business logic conflict
+422 Unprocessable Entity - When validation fails
+500 Internal Server Error - For unexpected errors
+```
+
+### 2. Custom Exception Classes
+
+- Define custom exception classes for common error scenarios (e.g., not found, insufficient stock, duplicate item).
+- Inherit from FastAPI's `HTTPException` for easy integration.
+
+Example custom exception:
+```
+class ItemNotFoundError(HTTPException):
+    def __init__(self, item_id: int):
+        super().__init__(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item with ID {item_id} not found",
+        )
+```
+
+### 3. Exception Handlers
+
+- Use FastAPI's `@app.exception_handler` to create global handlers for your custom exceptions.
+- Return structured error responses with details, error type, and timestamps.
+
+Example handler:
+```
+@app.exception_handler(ItemNotFoundError)
+async def item_not_found_handler(request: Request, exc: ItemNotFoundError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": "Item Not Found",
+            "message": exc.detail,
+            "timestamp": datetime.now().isoformat(),
+            "path": str(request.url.path)
+        }
+    )
+```
+
+### 4. Validation and Business Logic Errors
+
+- Use Pydantic for request validation and raise custom errors for business logic issues (e.g., insufficient stock, invalid transitions).
+- Customize error responses for better client experience.
+
+Example validation error:
+```
+@app.exception_handler(RequestValidationError)
+async def request_validation_error_handler(request: Request, exc: RequestValidationError):
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content={
+            "error": "Validation Error",
+            "message": "Invalid request data",
+            "details": exc.errors(),
+            "timestamp": datetime.now().isoformat(),
+            "path": str(request.url.path)
+        }
+    )
+```
+
+### 5. Logging and Monitoring
+
+- Use Python's `logging` module to log errors and important events.
+- Logging helps with debugging and monitoring your API in production.
+
+---
+
+## Next Steps
+
+- Try sending requests that trigger different error scenarios (e.g., not found, duplicate, validation errors).
+- Explore the code to see how exceptions and handlers are implemented.
+- Run the tests to ensure error handling works as expected!
+
+---
+
+**Tip:** FastAPI’s automatic docs are available at `/api/docs` when you run your app.
+
+---

workspace/7_framework/fastapi/day05/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_default_fixture_loop_scope = function
+pythonpath = . src

workspace/7_framework/fastapi/day05/requirements.txt

@@ -0,0 +1,8 @@
+fastapi>=0.115.0
+uvicorn>=0.30.0
+python-multipart>=0.0.20
+pytest>=7.0.0
+pytest-asyncio>=0.20.0
+pytest-cov>=4.0.0
+httpx>=0.24.0
+flake8>=5.0.0

workspace/7_framework/fastapi/day05/src/__init__.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+class OrderStatus(str, Enum):
+    pending = "pending"
+    processing = "processing"
+    shipped = "shipped"
+    delivered = "delivered"
+    cancelled = "cancelled"

workspace/7_framework/fastapi/day05/src/enums/__init__.py

@@ -0,0 +1,54 @@
+"""
+Global exceptions for the FastAPI application.
+"""
+
+from fastapi import HTTPException, status
+
+class ItemNotFoundError(HTTPException):
+    def __init__(self, item_id: int):
+        super().__init__(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Item with ID {item_id} not found",
+        )
+
+class InsufficientStockError(HTTPException):
+    def __init__(self, item_id: int, requested: int, available: int):
+        super().__init__(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Insufficient stock for item {item_id}. Requested: {requested}, Available: {available}"
+        )
+
+class DuplicateItemError(HTTPException):
+    def __init__(self, field: str, value: str):
+        super().__init__(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Item with ID {field} '{value}' already exists",
+        )
+
+class ValidationFailedError(HTTPException):
+    def __init__(self, errors: list):
+        super().__init__(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=errors,
+        )
+
+class UnauthorizedError(HTTPException):
+    def __init__(self):
+        super().__init__(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Unauthorized",
+        )
+
+class ForbiddenError(HTTPException):
+    def __init__(self):
+        super().__init__(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Forbidden",
+        )
+
+class InternalServerError(HTTPException):
+    def __init__(self):
+        super().__init__(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal Server Error",
+        )