APIException for FastAPI

Use ResponseModel to ensure that every API response (both successful and error states) follows a consistent JSON structure. This makes your API predictable for frontend consumers and simplifies OpenAPI/Swagger documentation.

Every response generated via ResponseModel includes the following fields:

• data: The actual payload (populated on success, null on failure).
• status: An ExceptionStatus value (e.g., SUCCESS, WARNING, FAIL).
• message: A short summary of the outcome.
• error_code: A specific error identifier (populated only if there is an error).
• description: Extra context for debugging.

Interpretation Logic:

• Success: data is populated and error_code is null.
• Failure: error_code is populated.
• Frontend Logic: Use the status field as the primary driver for application logic.

# Example of the resulting JSON structure
{
  "data": { "api_key": "valid_key" },
  "status": "SUCCESS",
  "message": "API key is valid",
  "error_code": null,
  "description": "The provided API key is valid."
}

To maintain a predictable and self-documenting API, you can define custom error codes by extending BaseExceptionCode. This allows you to organize unique, human-readable codes that clients can easily use to handle specific failure scenarios.

Each error code follows a specific tuple format: KEY = (code, message, description, rfc7807_type, rfc7807_instance)

• code (Required): The unique string identifier (e.g., "USR-404").
• message (Required): A short, human-readable error message.
• description (Optional): A detailed explanation of the error.
• rfc7807_type (Optional): The RFC 7807 error type.
• rfc7807_instance (Optional): The RFC 7807 error instance.

from api_exception import BaseExceptionCode

class CustomExceptionCode(BaseExceptionCode):
    # Format: KEY = (code, message, description, rfc7807_type, rfc7807_instance)
    #               # Req, # Req,   # Optional,  # Optional,   # Optional
    USER_NOT_FOUND = ("USR-404", "User not found.", "The user ID does not exist.")
    INVALID_API_KEY = ("API-401", "Invalid API key.", "Provide a valid API key.")
    PERMISSION_DENIED = ("PERM-403", "Permission denied.", "Access to this resource is forbidden.")

To use APIException, follow these three steps:

1. Register Handlers: Call register_exception_handlers(app) on your FastAPI instance. By default, it uses ResponseModel for formatting.
2. Define Custom Error Codes: Extend BaseExceptionCode to create your own domain-specific error codes.
3. Raise Exceptions: Use raise APIException(...) within your route handlers to trigger standardized error responses.

For successful responses, wrap your data in a ResponseModel to ensure the JSON structure remains consistent with your error responses.

from fastapi import FastAPI
from pydantic import BaseModel, Field
from api_exception import (
    register_exception_handlers,
    APIException,
    BaseExceptionCode,
    ResponseModel,
    APIResponse,
)

app = FastAPI()
register_exception_handlers(app)

class CustomExceptionCode(BaseExceptionCode):
    USER_NOT_FOUND = ("USR-404", "User not found.", "The user ID does not exist.")

class UserModel(BaseModel):
    id: int = Field(..., example=1)
    username: str = Field(..., example="John Doe")

@app.get(
    "/user/{user_id}",
    response_model=ResponseModel[UserModel],
    responses=APIResponse.default(),
)
async def user(user_id: int):
    if user_id == 1:
        raise APIException(
            error_code=CustomExceptionCode.USER_NOT_FOUND,
            http_status_code=404,
        )
    
    return ResponseModel[UserModel](
        data=UserModel(id=user_id, username="John Doe"),
        description="User retrieved successfully.",
    )

To use apiexception in an endpoint, follow these steps:

1. Define a Response Model: Use Pydantic's BaseModel to define the structure of your successful data.
2. Define Custom Exception Codes: Extend BaseExceptionCode to create domain-specific error codes. Each code is a tuple containing (error_code_string, short_message, detailed_description).
3. Configure the Endpoint:
   • Use ResponseModel[YourModel] as the response_model in the decorator.
   • Use APIResponse.default() in the responses parameter of the decorator to populate Swagger/OpenAPI documentation.
4. Raise Exceptions: Use raise APIException(...) with your custom code and an optional http_status_code to trigger a standardized error response.

from fastapi import FastAPI, Path
from pydantic import BaseModel, Field
from api_exception import APIException, register_exception_handlers, ResponseModel, APIResponse, BaseExceptionCode

app = FastAPI()

# 1. Register handlers
register_exception_handlers(app=app)

# 2. Create validation model
class UserResponse(BaseModel):
    id: int = Field(..., example=1, description="Unique identifier of the user")
    username: str = Field(..., example="Micheal Alice", description="Username or full name of the user")

# 3. Define custom exception codes
class CustomExceptionCode(BaseExceptionCode):
    USER_NOT_FOUND = ("USR-404", "User not found.", "The user ID does not exist.")

@app.get("/user/{user_id}",
    response_model=ResponseModel[UserResponse],
    responses=APIResponse.default()
)
async def user(user_id: int = Path()):
    if user_id == 1:
        # 4. Raise standardized exception
        raise APIException(
            error_code=CustomExceptionCode.USER_NOT_FOUND,
            http_status_code=401,
        )
    
    data = UserResponse(id=1, username="John Doe")
    return ResponseModel[UserResponse](
        data=data,
        description="User found and returned."
    )