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.