How to Return a Custom 404 Not Found Page Using FastAPI?

Introduction

When creating web applications, it's essential to handle HTTP status codes appropriately. One common status code you may encounter is 404 Not Found, which indicates that a requested resource could not be found. This article will explore various methods to return a custom 404 page using FastAPI, a modern Python framework for building web APIs.

Exception Handler Approach

FastAPI provides a convenient way to handle exceptions via its exception handling mechanism. You can define a custom handler for handling the 404 exception and return a custom response.

@app.exception_handler(404)
async def not_found_exception_handler(request: Request, exc: HTTPException):
    return RedirectResponse('https://fastapi.tiangolo.com')

Alternatively, you can use the exception_handlers parameter of the FastAPI class to register a global exception handler.

async def not_found_error(request: Request, exc: HTTPException):
    return RedirectResponse('https://fastapi.tiangolo.com')

exception_handlers = {404: not_found_error}
app = FastAPI(exception_handlers=exception_handlers)

Middleware Approach

Another approach is to create a middleware that intercepts HTTP responses and checks for the status code. If the status code is 404, the middleware can return a custom response before the response reaches the client.

@app.middleware("http")
async def redirect_on_not_found(request: Request, call_next):
    response = await call_next(request)
    if response.status_code == 404:
        return RedirectResponse("https://fastapi.tiangolo.com")
    else:
        return response

Custom Page Response

Using the methods mentioned above, you can return a simple redirect response. However, you can also create a more customized 404 page by defining a template and returning a TemplateResponse.

from fastapi.templating import Jinja2Templates

templates = Jinja2Templates(directory='templates')

async def not_found_error(request: Request, exc: HTTPException):
    return templates.TemplateResponse('404.html', {'request': request}, status_code=404)

In the templates directory, create a 404.html template with the desired content for your custom 404 page.

Conclusion

By leveraging exception handlers, middleware, or custom page responses, you can easily implement a custom 404 Not Found page in FastAPI. This allows you to provide a more user-friendly experience when a requested resource cannot be found, enhancing the overall user experience of your web application.