Response Handling in FastAPI: Models, Codes & Errors

Just as you validate and structure incoming requests, you must also control, sanitise, and format the data your API sends back. Returning raw internal data — with database IDs, hashed passwords, salary figures, or internal flags — is a common security mistake. FastAPI’s response_model parameter gives you a clean, declarative way to filter exactly what leaves your server, while HTTPException lets you abort with precise error responses at any point. This lesson covers both, plus custom response classes for those times when JSON isn’t what the client needs.

Outbound Data Serialization Flow

When a route function returns data, FastAPI filters it against the response schema, strips out any fields not declared in that schema, serialises the allowed fields to JSON, and sets the configured HTTP status code.

Response Models

By declaring a response_model in your path operation decorator, you tell FastAPI to:

Validate the output — ensure the return data conforms to the schema.
Serialize the data — convert complex Python objects (like database models) into JSON.
Filter private data — exclude any fields not declared in the response model.

Example: Sanitising Employee Data

Suppose your internal data contains private fields like base_salary and tax_id that you never want to expose to clients:

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()

# 1. Internal schema with sensitive fields
class EmployeeInternal(BaseModel):
    id: int
    name: str
    department: str
    base_salary: float
    tax_id: str

# 2. Public schema — only safe fields
class EmployeePublic(BaseModel):
    id: int
    name: str
    department: str

# Sample mock database
EMPLOYEES = {
    1: EmployeeInternal(id=1, name="Alice", department="Engineering", base_salary=8500.0, tax_id="TAX123"),
    2: EmployeeInternal(id=2, name="Bob", department="HR", base_salary=6000.0, tax_id="TAX456")
}

# 3. Use response_model to filter automatically
@app.get("/employees/{employee_id}", response_model=EmployeePublic)
def get_employee(employee_id: int):
    # Even though we return EmployeeInternal (with salary & tax_id),
    # FastAPI automatically strips those fields from the response!
    return EMPLOYEES.get(employee_id)

The client receives only:

{
    "id": 1,
    "name": "Alice",
    "department": "Engineering"
}

The base_salary and tax_id fields are never included in the response, regardless of what the function returns internally.

Without a response_model, FastAPI returns everything your function returns. Always declare a response_model for endpoints that touch internal or sensitive data.

Setting HTTP Status Codes

You can configure the default success status code for a route using the status_code parameter. Use the status module constants for readability and maintainability:

from fastapi import status

# Onboarding an employee should return 201 Created
@app.post(
    "/employees",
    response_model=EmployeePublic,
    status_code=status.HTTP_201_CREATED
)
def create_employee(employee: EmployeePublic):
    return employee

Always use status.HTTP_201_CREATED instead of the raw integer 201. It’s self-documenting and IDE-friendly — your editor will auto-complete the constant name and catch typos.

Raising HTTP Exceptions

When something goes wrong — a resource isn’t found, the caller lacks permission, a business rule is violated — raise an HTTPException to halt execution immediately and return a clear error response:

from fastapi import HTTPException

@app.get("/employees/{employee_id}", response_model=EmployeePublic)
def get_employee(employee_id: int):
    employee = EMPLOYEES.get(employee_id)

    if not employee:
        # Halt execution and return a 404 to the client
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Employee with ID {employee_id} does not exist"
        )

    return employee

The client receives:

{
    "detail": "Employee with ID 999 does not exist"
}

Common Exception Patterns

from fastapi import HTTPException, status

# 404 — Resource not found
raise HTTPException(
    status_code=status.HTTP_404_NOT_FOUND,
    detail="Employee not found"
)

# 400 — Bad request / business rule violation
raise HTTPException(
    status_code=status.HTTP_400_BAD_REQUEST,
    detail="Cannot transfer employee to the same department"
)

# 403 — Forbidden (authenticated but unauthorised)
raise HTTPException(
    status_code=status.HTTP_403_FORBIDDEN,
    detail="You do not have permission to modify this record"
)

# 409 — Conflict (duplicate resource)
raise HTTPException(
    status_code=status.HTTP_409_CONFLICT,
    detail="An employee with this email already exists"
)

Response Model Options

FastAPI provides extra parameters on response_model to fine-tune the output:

# Exclude fields that are None (optional fields not set)
@app.get("/employees/{employee_id}", response_model=EmployeePublic, response_model_exclude_none=True)
def get_employee(employee_id: int):
    ...

# Exclude specific fields by name
@app.get("/employees/{employee_id}", response_model=EmployeePublic, response_model_exclude={"department"})
def get_employee(employee_id: int):
    ...

# Include only specific fields
@app.get("/employees/{employee_id}", response_model=EmployeePublic, response_model_include={"id", "name"})
def get_employee(employee_id: int):
    ...

Custom Response Classes

Sometimes JSON isn’t the right format — you might need to return HTML, plain text, a file download, or a redirect. FastAPI supports this with response classes:

from fastapi.responses import HTMLResponse, FileResponse, RedirectResponse

# Return an HTML page
@app.get("/welcome", response_class=HTMLResponse)
def welcome_page():
    return """
    <html>
        <body>
            <h1>Employee Onboarding Dashboard</h1>
            <p>Welcome to the company portal!</p>
        </body>
    </html>
    """

# Redirect to another URL
@app.get("/old-endpoint")
def redirect_old():
    return RedirectResponse(url="/new-endpoint", status_code=301)

For JSON APIs, you rarely need to return a custom response class directly — FastAPI handles JSON serialisation for you. Custom response classes are most useful for file downloads, HTML rendering, and redirects.

Complete Example: Create and Retrieve with Filtering

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field

app = FastAPI()

class EmployeeCreate(BaseModel):
    name: str = Field(..., min_length=2)
    department: str
    salary: float = Field(..., gt=0)

class EmployeeResponse(BaseModel):
    id: int
    name: str
    department: str
    # salary is intentionally excluded from the response

EMPLOYEES: dict[int, dict] = {}

@app.post("/employees", response_model=EmployeeResponse, status_code=status.HTTP_201_CREATED)
def create_employee(employee: EmployeeCreate):
    new_id = len(EMPLOYEES) + 1
    EMPLOYEES[new_id] = {"id": new_id, **employee.model_dump()}
    return EMPLOYEES[new_id]  # salary is stripped by response_model

@app.get("/employees/{employee_id}", response_model=EmployeeResponse)
def get_employee(employee_id: int):
    if employee_id not in EMPLOYEES:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Employee {employee_id} not found"
        )
    return EMPLOYEES[employee_id]

SQL & Databases

Data Analysis

FastAPI

Frontend

Response Handling in FastAPI: Models, Codes & Errors

Outbound Data Serialization Flow

Response Models

Example: Sanitising Employee Data

Setting HTTP Status Codes

Raising HTTP Exceptions

Common Exception Patterns

Response Model Options

Custom Response Classes

Complete Example: Create and Retrieve with Filtering

​Outbound Data Serialization Flow

​Response Models

​Example: Sanitising Employee Data

​Setting HTTP Status Codes

​Raising HTTP Exceptions

​Common Exception Patterns

​Response Model Options

​Custom Response Classes

​Complete Example: Create and Retrieve with Filtering

Outbound Data Serialization Flow

Response Models

Example: Sanitising Employee Data

Setting HTTP Status Codes

Raising HTTP Exceptions

Common Exception Patterns

Response Model Options

Custom Response Classes

Complete Example: Create and Retrieve with Filtering