Custom exception handlers in FastAPI - Step-by-Step Execution

Concept Flow - Custom exception handlers

Request received

↓

Process request

↓

Exception occurs?

No→Return normal response

Yes↓

Catch exception

↓

Call custom exception handler

↓

Return custom error response

When a request causes an error, FastAPI catches it and calls your custom handler to return a special response.

Execution Sample

FastAPI

from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(HTTPException)
async def custom_http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(status_code=exc.status_code, content={"message": f"Oops! {exc.detail}"})

Defines a custom handler for HTTPException that returns a JSON message with a friendly error.

Execution Table

Step	Action	Exception Raised?	Handler Called	Response Returned
1	Request received for /items/42	No	No	Normal response with item data
2	Request received for /items/999	Yes (HTTPException 404)	Yes (custom_http_exception_handler)	JSONResponse with message 'Oops! Item not found'
3	Request received for /unknown	Yes (HTTPException 404)	Yes (custom_http_exception_handler)	JSONResponse with message 'Oops! Not Found'
4	Request received for /cause_error	Yes (ValueError)	No (default handler)	Default 500 Internal Server Error response

💡 Execution stops after returning the response from the handler or default error response.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4
request.url.path	/start	/items/999	/unknown	/cause_error
exc.status_code	None	404	404	None
exc.detail	None	Item not found	Not Found	ValueError raised
response.content.message	None	Oops! Item not found	Oops! Not Found	Default error message

Key Moments - 2 Insights

Why does the custom handler only catch HTTPException and not ValueError?

Because the handler is registered specifically for HTTPException (see execution_table rows 2 and 4). Other exceptions like ValueError use FastAPI's default handler.

What happens if no exception occurs during request processing?

The request is processed normally and a standard response is returned without calling any exception handler (see execution_table row 1).

Visual Quiz - 3 Questions

Look at the execution table, what response message is returned at step 3?

A "Item not found"

B "Oops! Not Found"

C "Default error message"

D "Normal response with item data"

💡 Hint

Check the 'Response Returned' column for step 3 in the execution_table.

At which step does the default error handler respond instead of the custom handler?

A Step 4

B Step 2

C Step 1

D Step 3

💡 Hint

Look for where 'Handler Called' is 'No' and 'Exception Raised?' is not HTTPException in the execution_table.

If you want to handle ValueError with a custom message, what should you do?

A Raise HTTPException instead of ValueError

B Modify the existing HTTPException handler

C Add a new @app.exception_handler(ValueError) function

D No changes needed, it is handled automatically

💡 Hint

Refer to how the HTTPException handler is registered in the code sample.

Concept Snapshot

Custom exception handlers in FastAPI:
- Use @app.exception_handler(ExceptionType) decorator
- Define async function with (request, exc) parameters
- Return a Response (e.g., JSONResponse) with custom content
- Only exceptions of the registered type trigger the handler
- Others use FastAPI's default error handling

Full Transcript

In FastAPI, when a request causes an error, the framework checks if a custom exception handler is registered for that error type. If yes, it calls that handler to create a special response. For example, a handler for HTTPException can return a JSON message with a friendly error. If no exception occurs, the request returns normally. If an exception occurs but no handler is registered, FastAPI returns a default error response. This lets you customize error messages for specific errors while keeping others default.