How to Customise Error Response for a Specific Route in FastAPI

In FastAPI, raising a RequestValidationError allows you to send a custom error response. This is useful for endpoints that require specific conditions to be met, such as a required Header.

Option 1: Override the default exception handler

This option allows you to override the default exception handler for RequestValidationError, allowing you to customize the Error response.

from fastapi import FastAPI, Request, Header, status
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()
routes_with_custom_exception = ['/']

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    if request.url.path in routes_with_custom_exception:
        return JSONResponse(content={'401': 'Unauthorized'}, status_code=401)
    
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content=jsonable_encoder({'detail': exc.errors(), 'body': exc.body}),
    )

Option 2: Use a sub-application

Creating a sub-application allows you to create a separate API instance with its own exception handler. This allows you to customize the error handling specifically for the sub-application.

from fastapi import FastAPI
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()
subapi = FastAPI()

@subapi.exception_handler(RequestValidationError)
async def validation_exception_handler(exc: RequestValidationError):
    return JSONResponse(content={'401': 'Unauthorized'}, status_code=401)
    
@subapi.get('/')
async def subapi_route(some_custom_header: str = Header(...)):
    return {'some-custom-header': some_custom_header}

app.mount('/sub', subapi)

Option 3: Use a custom APIRoute class

This method allows you to change the behavior of a specific route by using a custom APIRoute class.

from fastapi import FastAPI, APIRouter, Response, Request, Header, HTTPException
from fastapi.exceptions import RequestValidationError

class ValidationErrorHandlingRoute(APIRoute):
    def get_route_handler(self) -> Callable:
        original_route_handler = super().get_route_handler()

        async def custom_route_handler(request: Request) -> Response:
            try:
                return await original_route_handler(request)
            except RequestValidationError as e:
                raise HTTPException(status_code=401, detail='401 Unauthorized')

        return custom_route_handler

app = FastAPI()
router = APIRouter(route_class=ValidationErrorHandlingRoute)

@router.get('/custom')
async def custom_route(some_custom_header: str = Header(...)):
    return {'some-custom-header': some_custom_header}

app.include_router(router)

Which option should you use?

Option 1 is straightforward to implement when you only need to customize error response for specific routes. Option 2 is suitable when you want more control over the sub-area of your API, such as applying different security policies or exception handling. Option 3 gives you more control over individual routes and is useful for handling specific cases within a route.