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.

Practice

1. What is the main purpose of a custom exception handler in FastAPI?

easy

A. To catch specific errors and return user-friendly responses

B. To speed up the server response time

C. To automatically fix bugs in the code

D. To log all incoming requests

Solution

1. Step 1: Understand what exception handlers do

   They catch errors that happen during request processing.

2. Step 2: Identify the benefit of custom handlers

   They allow sending clear, friendly messages instead of default error pages.

3. Final Answer:

   To catch specific errors and return user-friendly responses -> Option A

4. Quick Check:

   Custom handlers improve user experience = B [OK]

Hint: Custom handlers catch errors and explain them clearly [OK]

Common Mistakes:

• Thinking they fix bugs automatically
• Confusing with logging or performance tools
• Assuming they speed up requests

2. Which of the following is the correct way to register a custom exception handler in FastAPI?

easy

A. app.add_exception_handler(MyException, handler_function)

B. app.register_handler(MyException, handler_function)

C. app.use_exception_handler(MyException, handler_function)

D. app.exception_handler(MyException, handler_function)

Solution

1. Step 1: Recall FastAPI method for adding handlers

   FastAPI uses add_exception_handler to register handlers.

2. Step 2: Check method names in options

   Only app.add_exception_handler(MyException, handler_function) uses the correct method name and parameters.

3. Final Answer:

   app.add_exception_handler(MyException, handler_function) -> Option A

4. Quick Check:

   Correct method is add_exception_handler = D [OK]

Hint: Use add_exception_handler to register custom handlers [OK]

Common Mistakes:

• Using wrong method names like register_handler
• Confusing decorator syntax with registration
• Passing wrong parameters order

3. Given this code snippet, what will be the HTTP status code returned when MyException is raised?

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

app = FastAPI()

class MyException(Exception):
    pass

@app.exception_handler(MyException)
async def my_exception_handler(request: Request, exc: MyException):
    return JSONResponse(status_code=418, content={"message": "Custom error occurred"})

@app.get("/test")
async def test():
    raise MyException()

medium

A. 404

B. 418

C. 200

D. 500

Solution

1. Step 1: Identify the status code in the handler

   The handler returns a JSONResponse with status_code=418.

2. Step 2: Understand what happens when exception is raised

   Raising MyException triggers the handler, which sends the 418 status.

3. Final Answer:

   418 -> Option B

4. Quick Check:

   Handler sets status 418 = A [OK]

Hint: Check the status_code in JSONResponse inside handler [OK]

Common Mistakes:

• Assuming default 500 error code
• Confusing 404 with missing route
• Ignoring custom status_code in handler

4. What is wrong with this FastAPI custom exception handler code?

from fastapi import FastAPI

app = FastAPI()

class CustomError(Exception):
    pass

@app.exception_handler(CustomError)
def handler(exc: CustomError):
    return {"error": "Something went wrong"}

medium

A. Return value must be a string, not a dict

B. Exception class must inherit from HTTPException

C. Handler function must be async and accept Request parameter

D. Decorator should be @app.add_exception_handler, not @app.exception_handler

Solution

1. Step 1: Check handler function signature

   FastAPI expects async handler with parameters (Request, Exception).

2. Step 2: Identify missing Request and async

   The handler lacks the Request parameter and is not async.

3. Final Answer:

   Handler function must be async and accept Request parameter -> Option C

4. Quick Check:

   Handler signature requires async and Request = C [OK]

Hint: Handler must be async and take Request as first argument [OK]

Common Mistakes:

• Making handler synchronous
• Omitting Request parameter
• Thinking exception must inherit HTTPException

5. You want to create a custom exception handler in FastAPI that returns a JSON response with a dynamic message and a 400 status code whenever ValueError is raised. Which code snippet correctly implements this?

hard

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

app = FastAPI()

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
return JSONResponse(content={"error": str(exc)}, status=400)

B. from fastapi import FastAPI

app = FastAPI()

@app.exception_handler(ValueError)
def value_error_handler(exc: ValueError):
return {"error": str(exc), "status": 400}

C. from fastapi import FastAPI, Request

app = FastAPI()

@app.add_exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
return {"error": str(exc), "status_code": 400}

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

app = FastAPI()

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
return JSONResponse(status_code=400, content={"error": str(exc)})

Solution

1. Step 1: Check correct decorator and function signature

   Use @app.exception_handler with async function taking (Request, Exception).

2. Step 2: Verify JSONResponse usage and status code

   Return JSONResponse with status_code=400 and content with error message.

3. Step 3: Identify correct option

   from fastapi import FastAPI, Request from fastapi.responses import JSONResponse app = FastAPI() @app.exception_handler(ValueError) async def value_error_handler(request: Request, exc: ValueError): return JSONResponse(status_code=400, content={"error": str(exc)}) matches all requirements exactly.

4. Final Answer:

   A -> Option D

5. Quick Check:

   Correct async handler with JSONResponse and status_code=400 = A [OK]

Hint: Use async handler with JSONResponse and status_code param [OK]

Common Mistakes:

• Using synchronous handler
• Missing Request parameter
• Wrong decorator or status code parameter name
• Returning dict instead of JSONResponse