Custom error response models in FastAPI - Step-by-Step Execution

Concept Flow - Custom error response models

Client sends request

↓

API endpoint receives request

↓

Process request

↓

Error occurs?

No→Return success response

Yes↓

Raise HTTPException with custom error model

↓

FastAPI catches exception

↓

Return custom error response to client

This flow shows how FastAPI handles a request, detects an error, and returns a custom error response model to the client.

Execution Sample

FastAPI

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class ErrorResponse(BaseModel):
    detail: str

@app.get("/items/{item_id}", responses={404: {"model": ErrorResponse}})
async def read_item(item_id: int):
    if item_id != 42:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id}

This code defines a FastAPI endpoint that returns a custom error response model when the item is not found.

Execution Table

Step	Action	Input	Condition	Result	Response Sent
1	Receive request	GET /items/10	N/A	Start processing	None
2	Check item_id	item_id=10	item_id != 42	Condition True	None
3	Raise HTTPException	status_code=404, detail='Item not found'	Error raised	Exception caught by FastAPI	None
4	Return error response	Use ErrorResponse model	N/A	Serialize error detail	{"detail": "Item not found"} with 404 status
5	Client receives response	HTTP 404	N/A	Error message displayed	Error JSON with detail

💡 Execution stops after sending the custom error response when item_id is not 42.

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
item_id	N/A	10	10	10
exception	None	None	HTTPException(status_code=404, detail='Item not found')	HTTPException instance

Key Moments - 2 Insights

Why does FastAPI return a JSON error response instead of a plain text error?

Because the endpoint defines a custom error response model (ErrorResponse), FastAPI uses it to format the error detail as JSON, as shown in execution_table step 4.

What happens if the item_id equals 42?

The condition in step 2 is false, so no exception is raised and the endpoint returns a success response with the item_id.

Visual Quiz - 3 Questions

Look at the execution table, what is the response sent at step 4?

A A success response with item_id

B A JSON error with detail 'Item not found' and status 404

C A plain text error message

D No response sent yet

💡 Hint

Check the 'Response Sent' column at step 4 in the execution_table.

At which step does FastAPI catch the HTTPException?

A Step 3

B Step 4

C Step 2

D Step 5

💡 Hint

Look at the 'Result' column to see when the exception is caught.

If item_id is 42, what changes in the execution table?

A Step 3 raises a different exception

B Step 4 returns an error response anyway

C Step 2 condition becomes false and no error is raised

D Execution stops at step 1

💡 Hint

Refer to the 'Condition' column at step 2 and the key_moments section.

Concept Snapshot

FastAPI custom error response models:
- Define a Pydantic model for error details
- Use responses parameter in route decorator to link status code to model
- Raise HTTPException with status and detail
- FastAPI returns JSON error using your model
- Helps clients understand errors clearly

Full Transcript

This example shows how FastAPI handles custom error responses. When a client requests an item by ID, the API checks if the ID matches a specific value. If not, it raises an HTTPException with status 404 and a detail message. The route decorator specifies a custom error response model, so FastAPI formats the error as JSON using that model. The execution table traces each step: receiving the request, checking the condition, raising the exception, FastAPI catching it, and sending the JSON error response. Variables like item_id and the exception instance are tracked through the steps. Key moments clarify why JSON is returned and what happens when the item is found. The quiz tests understanding of response content, exception handling step, and condition effects. This approach helps beginners see how custom error models work in FastAPI step-by-step.

Practice

1. What is the main purpose of using custom error response models in FastAPI?

easy

A. To define a clear and consistent structure for error messages returned by the API

B. To speed up the API response time

C. To automatically fix errors in the API code

D. To hide all error messages from the client

Solution

1. Step 1: Understand error response models

   Custom error response models define how error messages look, making them clear and consistent.

2. Step 2: Identify the purpose in FastAPI

   FastAPI uses these models to send structured error info to clients, improving API usability.

3. Final Answer:

   To define a clear and consistent structure for error messages returned by the API -> Option A

4. Quick Check:

   Custom error models = clear error messages [OK]

Hint: Custom error models shape error messages clearly [OK]

Common Mistakes:

• Thinking they speed up API responses
• Believing they fix code errors automatically
• Assuming they hide errors completely

2. Which of the following is the correct way to define a custom error response model using Pydantic in FastAPI?

easy

A. class ErrorResponse: message = str; code = int

B. class ErrorResponse(BaseModel): message: str; code: int

C. ErrorResponse = {'message': str, 'code': int}

D. def ErrorResponse(message: str, code: int): return {'message': message, 'code': code}

Solution

1. Step 1: Recognize Pydantic model syntax

   Pydantic models are defined as classes inheriting from BaseModel with typed attributes.

2. Step 2: Match correct syntax

   class ErrorResponse(BaseModel): message: str; code: int correctly defines a class with typed fields using BaseModel.

3. Final Answer:

   class ErrorResponse(BaseModel): message: str; code: int -> Option B

4. Quick Check:

   Pydantic model = class with BaseModel [OK]

Hint: Use class with BaseModel and typed fields [OK]

Common Mistakes:

• Defining models as functions
• Using plain dictionaries instead of classes
• Missing BaseModel inheritance

3. Given this FastAPI code snippet, what will be the response when a ValueError is raised?

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

app = FastAPI()

class ErrorResponse(BaseModel):
    detail: str

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content=ErrorResponse(detail=str(exc)).dict()
    )

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

medium

A. Empty response with status 204

B. Plain text 'Invalid input' with status 500

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

D. JSON with key 'error' and message 'Invalid input' with status 400

Solution

1. Step 1: Understand exception handler behavior

   The handler catches ValueError and returns JSONResponse with ErrorResponse model content and status 400.

2. Step 2: Check response content and status

   The content is the dict form of ErrorResponse with detail set to the exception message, so JSON has key 'detail' with 'Invalid input'.

3. Final Answer:

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

4. Quick Check:

   Exception handler returns JSON with detail key [OK]

Hint: Exception handler returns model dict as JSON with status [OK]

Common Mistakes:

• Expecting plain text instead of JSON
• Confusing status codes
• Assuming different JSON key names

4. Identify the error in this FastAPI custom error handler code:

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

app = FastAPI()

class ErrorResponse(BaseModel):
    message: str

@app.exception_handler(KeyError)
async def key_error_handler(request: Request, exc: KeyError):
    return JSONResponse(
        status_code=404,
        content=ErrorResponse(message=exc).dict()
    )

medium

A. Missing BaseModel inheritance in ErrorResponse

B. Exception handler must be synchronous, not async

C. Using status code 404 instead of 400

D. Passing the exception object directly instead of converting to string

Solution

1. Step 1: Check how exception is passed to model

   The code passes exc (KeyError object) directly to message field which expects a string.

2. Step 2: Identify correct usage

   It should convert exc to string with str(exc) to avoid type errors.

3. Final Answer:

   Passing the exception object directly instead of converting to string -> Option D

4. Quick Check:

   Exception message must be string [OK]

Hint: Convert exception to string before passing to model [OK]

Common Mistakes:

• Passing exception object without str()
• Confusing async/sync handler rules
• Incorrect status code choice

5. You want to create a FastAPI app that returns a custom error response with fields error_code (int) and error_msg (str) whenever a RuntimeError occurs. Which of the following code snippets correctly implements this behavior?

hard

A. class CustomError(BaseModel): error_code: int; error_msg: str

@app.exception_handler(RuntimeError)
async def runtime_error_handler(request: Request, exc: RuntimeError):
return JSONResponse(status_code=500, content=CustomError(error_code=1001, error_msg=str(exc)).dict())

B. class CustomError(BaseModel): error_code: str; error_msg: int

@app.exception_handler(RuntimeError)
async def runtime_error_handler(request: Request, exc: RuntimeError):
return JSONResponse(status_code=400, content=CustomError(error_code='1001', error_msg=exc).dict())

C. class CustomError:
def __init__(self, error_code, error_msg):
self.error_code = error_code
self.error_msg = error_msg

@app.exception_handler(RuntimeError)
async def runtime_error_handler(request: Request, exc: RuntimeError):
return JSONResponse(status_code=500, content=CustomError(1001, str(exc)))

D. @app.exception_handler(RuntimeError)
async def runtime_error_handler(request: Request, exc: RuntimeError):
return JSONResponse(status_code=500, content={'error_code': 1001, 'error_msg': str(exc)})

Solution

1. Step 1: Define correct Pydantic model

   class CustomError(BaseModel): error_code: int; error_msg: str @app.exception_handler(RuntimeError) async def runtime_error_handler(request: Request, exc: RuntimeError): return JSONResponse(status_code=500, content=CustomError(error_code=1001, error_msg=str(exc)).dict()) defines CustomError inheriting from BaseModel with correct field types (int and str).

2. Step 2: Implement exception handler properly

   class CustomError(BaseModel): error_code: int; error_msg: str @app.exception_handler(RuntimeError) async def runtime_error_handler(request: Request, exc: RuntimeError): return JSONResponse(status_code=500, content=CustomError(error_code=1001, error_msg=str(exc)).dict())'s handler returns JSONResponse with status 500 and content as dict from CustomError instance, converting exception to string.

3. Step 3: Check other options for errors

   class CustomError(BaseModel): error_code: str; error_msg: int @app.exception_handler(RuntimeError) async def runtime_error_handler(request: Request, exc: RuntimeError): return JSONResponse(status_code=400, content=CustomError(error_code='1001', error_msg=exc).dict()) swaps types incorrectly and passes exc without str(); class CustomError: def __init__(self, error_code, error_msg): self.error_code = error_code self.error_msg = error_msg @app.exception_handler(RuntimeError) async def runtime_error_handler(request: Request, exc: RuntimeError): return JSONResponse(status_code=500, content=CustomError(1001, str(exc))) uses plain class not BaseModel and returns object not dict; @app.exception_handler(RuntimeError) async def runtime_error_handler(request: Request, exc: RuntimeError): return JSONResponse(status_code=500, content={'error_code': 1001, 'error_msg': str(exc)}) skips model usage.

4. Final Answer:

   Option A correctly defines model and handler returning proper JSON response -> Option A

5. Quick Check:

   Use BaseModel with typed fields and dict() in handler [OK]

Hint: Use BaseModel and dict() for error response content [OK]

Common Mistakes:

• Swapping field types in model
• Not converting exception to string
• Returning model instance instead of dict
• Skipping Pydantic model for error response