Global exception middleware in FastAPI - Step-by-Step Execution

Concept Flow - Global exception middleware

Request received

↓

Middleware intercepts request

↓

Try to process request

↓

Return [Catch exception

↓

Create error response

↓

Return error response

↓

Response sent

The middleware catches all exceptions during request processing and returns a custom error response instead of crashing.

Execution Sample

FastAPI

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

app = FastAPI()

@app.middleware("http")
async def global_exception_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
        return response
    except Exception as e:
        return JSONResponse(status_code=500, content={"detail": str(e)})

This middleware catches any exception from downstream handlers and returns a JSON error response with status 500.

Execution Table

Step	Action	Try Block Result	Exception Caught	Response Returned
1	Request received by middleware	No result yet	No	No response yet
2	call_next(request) called	Handler runs normally	No	Handler's normal response
3	Middleware returns normal response	N/A	No	Normal response sent
4	Request received by middleware	No result yet	No	No response yet
5	call_next(request) called	Exception raised in handler	Yes	No response yet
6	Exception caught in except block	N/A	Yes	Prepare JSON error response
7	Middleware returns JSON error response	N/A	Yes	Error response sent

💡 Execution stops after middleware returns either normal or error response.

Variable Tracker

Variable	Start	After Step 2	After Step 5	Final
request	Incoming HTTP request object	Same request passed to handler	Same request passed to handler	Same request
response	None	Normal response from handler	None (exception raised)	Response returned (normal or error)
e (exception)	None	None	Exception instance caught	Exception handled and response created

Key Moments - 3 Insights

Why does the middleware use try-except around call_next(request)?

Because call_next runs the next handler which might raise an exception. The try-except catches it to prevent server crash and return a friendly error response (see execution_table rows 5-7).

What happens if no exception occurs in the handler?

The middleware simply returns the normal response from the handler without modification (see execution_table rows 2-3).

Can the middleware catch exceptions from any route handler?

Yes, because it wraps all requests globally before they reach any route (see concept_flow).

Visual Quiz - 3 Questions

Look at the execution_table, what is the response returned at step 3?

A A JSON error response with status 500

B No response yet

C The normal response from the handler

D An exception object

💡 Hint

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

At which step does the middleware catch an exception?

A Step 6

B Step 4

C Step 5

D Step 2

💡 Hint

Look for 'Exception caught in except block' in the 'Action' column of the execution_table.

If the handler never raises an exception, how many steps in the execution_table show exception handling?

A Two steps

B Zero steps

C One step

D Three steps

💡 Hint

Check the 'Exception Caught' column for 'Yes' entries when no exception occurs.

Concept Snapshot

Global exception middleware in FastAPI:
- Wraps all requests with @app.middleware("http")
- Uses try-except around call_next(request)
- Returns normal response if no error
- Returns JSON error response with status 500 if exception
- Prevents server crash and gives friendly error messages

Full Transcript

Global exception middleware in FastAPI intercepts every HTTP request before it reaches route handlers. It uses a try-except block around the call_next function that calls the next handler. If the handler runs without errors, the middleware returns the normal response. If an exception occurs, the middleware catches it and returns a JSON response with status code 500 and the error details. This prevents the server from crashing and provides a consistent error response. The execution table shows the step-by-step flow of request handling, exception catching, and response returning. Variables like request, response, and exception instance change state as the middleware processes the request. Key moments clarify why try-except is needed and how the middleware works globally. The quiz tests understanding of response flow and exception handling steps.

Practice

1. What is the main purpose of global exception middleware in a FastAPI application?

easy

A. To automatically generate API documentation

B. To speed up the API response time by caching results

C. To manage database connections efficiently

D. To catch and handle errors for the entire application in one place

Solution

1. Step 1: Understand middleware role

   Middleware runs for every request and can intercept errors globally.

2. Step 2: Identify purpose of global exception middleware

   It catches errors from any part of the app and handles them centrally.

3. Final Answer:

   To catch and handle errors for the entire application in one place -> Option D

4. Quick Check:

   Global error handling = catch all errors [OK]

Hint: Global middleware handles all errors in one place [OK]

Common Mistakes:

• Confusing middleware with caching or documentation
• Thinking it manages database connections
• Assuming it only handles specific routes

2. Which of the following is the correct way to add a global exception middleware in FastAPI?

easy

A. app.use_middleware(ExceptionMiddleware, handler=custom_handler)

B. app.add_middleware(ExceptionMiddleware, handler=custom_handler)

C. app.middleware(ExceptionMiddleware, handler=custom_handler)

D. app.register_middleware(ExceptionMiddleware, handler=custom_handler)

Solution

1. Step 1: Recall FastAPI middleware syntax

   FastAPI uses add_middleware method to add middleware.

2. Step 2: Match correct method name

   Only add_middleware is valid; others are incorrect method names.

3. Final Answer:

   app.add_middleware(ExceptionMiddleware, handler=custom_handler) -> Option B

4. Quick Check:

   Use add_middleware() to add middleware [OK]

Hint: Use add_middleware() method to add middleware [OK]

Common Mistakes:

• Using incorrect method names like use_middleware or register_middleware
• Confusing middleware with route decorators
• Missing required parameters in add_middleware

3. Given this FastAPI middleware code snippet, what will be the response if a ValueError is raised inside a route?

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

app = FastAPI()

@app.middleware("http")
async def catch_exceptions_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
        return response
    except ValueError as e:
        return JSONResponse(status_code=400, content={"error": str(e)})

@app.get("/test")
async def test_route():
    raise ValueError("Invalid input")

medium

A. {"detail": "ValueError"} with status 422

B. 500 Internal Server Error with default HTML page

C. {"error": "Invalid input"} with status 400

D. Empty response with status 200

Solution

1. Step 1: Analyze middleware error handling

   The middleware catches ValueError and returns JSONResponse with status 400 and error message.

2. Step 2: Check route behavior

   The route raises ValueError("Invalid input"), triggering the middleware's except block.

3. Final Answer:

   {"error": "Invalid input"} with status 400 -> Option C

4. Quick Check:

   Middleware catches ValueError and returns JSON error [OK]

Hint: Middleware catches ValueError and returns JSON with status 400 [OK]

Common Mistakes:

• Assuming default 500 error instead of custom JSON response
• Confusing status codes 422 and 400
• Ignoring middleware and expecting normal route error

4. Identify the error in this FastAPI global exception middleware code:

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

app = FastAPI()

@app.middleware("http")
async def exception_middleware(request: Request, call_next):
    try:
        response = call_next(request)
        return response
    except Exception as e:
        return JSONResponse(status_code=500, content={"error": "Server error"})

medium

A. Missing await before call_next(request)

B. Incorrect exception type used

C. JSONResponse should not be returned in middleware

D. Middleware should not catch exceptions

Solution

1. Step 1: Check async call to call_next

   call_next is an async function and must be awaited.

2. Step 2: Identify missing await

   Code calls call_next(request) without await, causing a coroutine object to be returned instead of response.

3. Final Answer:

   Missing await before call_next(request) -> Option A

4. Quick Check:

   Always await async call_next() in middleware [OK]

Hint: Always await call_next(request) in async middleware [OK]

Common Mistakes:

• Forgetting to await async call_next
• Thinking JSONResponse can't be returned in middleware
• Believing middleware shouldn't catch exceptions

5. You want to create a global exception middleware in FastAPI that logs all exceptions and returns a JSON error with status 500. Which code snippet correctly implements this behavior?

hard

A. @app.middleware('http')
async def global_exception(request, call_next):
try:
return await call_next(request)
except Exception as e:
print(f"Error: {e}")
return JSONResponse(status_code=500, content={"error": "Internal server error"})

B. app.add_middleware(ExceptionMiddleware, handler=lambda req, exc: JSONResponse({"error": str(exc)}, status_code=500))

C. @app.exception_handler(Exception)
async def global_exception_handler(request, exc):
return JSONResponse(status_code=500, content={"error": str(exc)})

D. app.add_exception_handler(Exception, lambda request, exc: JSONResponse({"error": "Error occurred"}, status_code=500))

Solution

1. Step 1: Understand middleware vs exception handler

   Middleware wraps all requests and can catch exceptions globally; exception handlers are per-exception but not middleware.

2. Step 2: Check for logging and JSON response in middleware

   @app.middleware('http') async def global_exception(request, call_next): try: return await call_next(request) except Exception as e: print(f"Error: {e}") return JSONResponse(status_code=500, content={"error": "Internal server error"}) uses @app.middleware('http') with try-except, logs error with print, and returns JSONResponse with status 500.

3. Step 3: Verify other options

   app.add_middleware(ExceptionMiddleware, handler=lambda req, exc: JSONResponse({"error": str(exc)}, status_code=500)) uses add_middleware incorrectly; C and D are exception handlers, not middleware.

4. Final Answer:

   @app.middleware('http') async def global_exception(request, call_next): try: return await call_next(request) except Exception as e: print(f"Error: {e}") return JSONResponse(status_code=500, content={"error": "Internal server error"}) -> Option A

5. Quick Check:

   Middleware with try-except and logging = @app.middleware('http') async def global_exception(request, call_next): try: return await call_next(request) except Exception as e: print(f"Error: {e}") return JSONResponse(status_code=500, content={"error": "Internal server error"}) [OK]

Hint: Use @app.middleware('http') with try-except and logging [OK]

Common Mistakes:

• Confusing middleware with exception handlers
• Using add_middleware incorrectly for exceptions
• Not logging exceptions inside middleware