By WebNest Studio Engineering Team
Python Tutorial
Response Models, Status Codes and Error Handling
A good API is predictable about what it returns. FastAPI lets you declare the response model of each endpoint so that output is validated, documented and — importantly — filtered, which stops internal fields such as password hashes from leaking. You also choose the right status code for each outcome and turn failures into clean JSON errors with HTTPException and custom exception handlers.
Why it matters
What an API sends back is a contract with its clients. Returning the right status code tells them what happened, a response model guarantees that internal fields such as password hashes never leak, and consistent error responses let client code handle failures properly. These details separate a toy API from a professional one.
Response Models
Declare the return type (-> UserOut) or pass response_model=UserOut. FastAPI converts whatever you return into that model, drops fields that are not in it, validates the result and documents it in /docs. A common pattern is three models per resource: UserCreate (input with password), UserInDB (stored, with the hash) and UserOut (public). Use list[UserOut] for collections and response_model_exclude_none=True to omit empty fields.
Status Codes
200 OK— successful read or update (the default).201 Created— a new resource was created:@app.post(..., status_code=201).204 No Content— success with no body, typical for DELETE.400 Bad Request,401 Unauthorized,403 Forbidden,404 Not Found,409 Conflict— client errors you raise yourself.422 Unprocessable Content— automatic validation errors.500— unhandled server errors.- Use the named constants in
fastapi.status, e.g.status.HTTP_404_NOT_FOUND, for readability.
Raising and Handling Errors
raise HTTPException(status_code=404, detail="Book not found") stops the request and returns {"detail": "Book not found"}; headers= can add headers. For domain errors, define your own exception classes and register a handler with @app.exception_handler(MyError) that returns a JSONResponse — your business code stays free of HTTP details. You can also customise the format of validation errors by handling RequestValidationError.
Examples
Filtering sensitive fields with response models
import hashlib
from fastapi import FastAPI, status
from fastapi.testclient import TestClient
from pydantic import BaseModel
app = FastAPI()
users = []
class UserCreate(BaseModel):
username: str
email: str
password: str
class UserOut(BaseModel):
id: int
username: str
email: str
@app.post("/users", status_code=status.HTTP_201_CREATED)
def register(user: UserCreate) -> UserOut:
stored = {
"id": len(users) + 1,
"username": user.username,
"email": user.email,
"password_hash": hashlib.sha256(user.password.encode()).hexdigest(), # demo only
"is_admin": False,
}
users.append(stored)
return stored # extra keys are filtered out by UserOut
@app.get("/users", response_model=list[UserOut])
def list_users():
return users
client = TestClient(app)
r = client.post("/users", json={"username": "asha", "email": "asha@example.com", "password": "s3cret!"})
print(r.status_code, r.json())
print(client.get("/users").json())
201 {'id': 1, 'username': 'asha', 'email': 'asha@example.com'}
[{'id': 1, 'username': 'asha', 'email': 'asha@example.com'}]
HTTPException, 204 responses and custom headers
from fastapi import FastAPI, HTTPException, Response, status
from fastapi.testclient import TestClient
app = FastAPI()
books = {1: "Python Basics", 2: "Deep Python"}
@app.get("/books/{book_id}")
def get_book(book_id: int):
if book_id not in books:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Book {book_id} not found")
return {"id": book_id, "title": books[book_id]}
@app.post("/books", status_code=status.HTTP_201_CREATED)
def add_book(title: str, response: Response):
if title in books.values():
raise HTTPException(status.HTTP_409_CONFLICT, detail="A book with this title already exists")
book_id = max(books) + 1
books[book_id] = title
response.headers["Location"] = f"/books/{book_id}"
return {"id": book_id, "title": title}
@app.delete("/books/{book_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_book(book_id: int):
if books.pop(book_id, None) is None:
raise HTTPException(status.HTTP_404_NOT_FOUND, detail="Book not found")
client = TestClient(app)
print(client.get("/books/1").json())
r = client.get("/books/9")
print(r.status_code, r.json())
r = client.post("/books?title=SQL Basics")
print(r.status_code, r.json(), r.headers["location"])
print(client.post("/books?title=Deep Python").json())
r = client.delete("/books/2")
print(r.status_code, repr(r.text))
print(client.delete("/books/2").status_code)
{'id': 1, 'title': 'Python Basics'}
404 {'detail': 'Book 9 not found'}
201 {'id': 3, 'title': 'SQL Basics'} /books/3
{'detail': 'A book with this title already exists'}
204 ''
404
Custom exceptions with exception handlers
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
class InsufficientStock(Exception):
def __init__(self, product, available):
self.product = product
self.available = available
app = FastAPI()
STOCK = {"pen": 5, "lamp": 0}
@app.exception_handler(InsufficientStock)
async def stock_handler(request: Request, exc: InsufficientStock):
return JSONResponse(status_code=409, content={
"error": "insufficient_stock", "product": exc.product, "available": exc.available,
})
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
fields = [".".join(str(p) for p in e["loc"][1:]) for e in exc.errors()]
return JSONResponse(status_code=422, content={"error": "invalid_input", "fields": fields})
def reserve(product, quantity): # business logic: no HTTP details here
if STOCK.get(product, 0) < quantity:
raise InsufficientStock(product, STOCK.get(product, 0))
STOCK[product] -= quantity
return STOCK[product]
@app.post("/reserve/{product}")
def reserve_endpoint(product: str, quantity: int):
return {"product": product, "left": reserve(product, quantity)}
client = TestClient(app)
print(client.post("/reserve/pen?quantity=2").json())
r = client.post("/reserve/lamp?quantity=1")
print(r.status_code, r.json())
r = client.post("/reserve/pen?quantity=lots")
print(r.status_code, r.json())
{'product': 'pen', 'left': 3}
409 {'error': 'insufficient_stock', 'product': 'lamp', 'available': 0}
422 {'error': 'invalid_input', 'fields': ['quantity']}
Common Mistakes
- Returning database rows directly without a response model and leaking password hashes or internal flags.
- Returning 200 for everything, or 500 for client mistakes.
- Returning an error dict with status 200 instead of raising HTTPException.
- Sending a body with 204 No Content responses.
- Scattering HTTP status logic through business code instead of using custom exceptions and handlers.
Exercise
Add two endpoints. POST /users accepts a name and a password, stores the user, responds with status 201 and returns only the name. GET /users/{name} returns the user's name, or a 404 error with the detail User not found.
Expected output: 201 {'name': 'asha'} then 404 {'detail': 'User not found'}
from fastapi import FastAPI, HTTPException
from fastapi.testclient import TestClient
from pydantic import BaseModel
app = FastAPI()
users = {}
class UserIn(BaseModel):
name: str
password: str
class UserOut(BaseModel):
name: str
# TODO: POST /users with response_model=UserOut and status_code=201
# TODO: GET /users/{name} with response_model=UserOut, raising HTTPException(404) if missing
client = TestClient(app)
response = client.post("/users", json={"name": "asha", "password": "secret"})
print(response.status_code, response.json())
response = client.get("/users/ravi")
print(response.status_code, response.json())
Show hints
- Both options go in the decorator:
@app.post("/users", response_model=UserOut, status_code=201). - Raise the error with
raise HTTPException(status_code=404, detail="User not found").
Show solution
from fastapi import FastAPI, HTTPException
from fastapi.testclient import TestClient
from pydantic import BaseModel
app = FastAPI()
users = {}
class UserIn(BaseModel):
name: str
password: str
class UserOut(BaseModel):
name: str
@app.post("/users", response_model=UserOut, status_code=201)
def create_user(user: UserIn):
users[user.name] = user
return user
@app.get("/users/{name}", response_model=UserOut)
def read_user(name: str):
if name not in users:
raise HTTPException(status_code=404, detail="User not found")
return users[name]
client = TestClient(app)
response = client.post("/users", json={"name": "asha", "password": "secret"})
print(response.status_code, response.json())
response = client.get("/users/ravi")
print(response.status_code, response.json())
Quick quiz
1. Which status code should a successful POST that creates a resource return?
- A. 200
- B. 302
- C. 204
- D. 201
Show answer
D. 201 means Created. 204 means success with no response body.
2. What does response_model do?
- A. Filters and validates the data returned, so only the declared fields are sent
- B. Validates the request
- C. Sets the status code
- D. Caches the response
Show answer
A. Fields not in the response model, such as a password, are removed.
3. How is an error response sent from inside a path operation?
- A. return 404
- B. raise HTTPException(status_code=404, detail="...")
- C. print("error")
- D. return None
Show answer
B. FastAPI converts the exception into a JSON response with that status.
Interview questions
Why use separate models for input and output?
Show answer
The data a client sends and the data the API returns are rarely the same. Input may include a password that must never be returned; output may include an id and timestamps that the client cannot set. Separate models make each direction explicit, and declaring the output model as response_model guarantees that only its fields leave the server, even if the function returns an object with more.
What is the difference between 401 and 403?
Show answer
401 Unauthorized means the request has no valid credentials: the client is not logged in, or its token is missing or expired, and it should authenticate. 403 Forbidden means the client is identified but is not allowed to perform this action, and authenticating again will not help.
Key Points to Remember
- Response models validate, document and filter output — separate input and output models.
- Choose status codes deliberately: 201 for create, 204 for delete, 404/409 for client errors.
- HTTPException returns {"detail": ...} with the status you choose.
- Custom exceptions plus @app.exception_handler keep business logic independent of HTTP.
- RequestValidationError handlers let you customise 422 responses.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. A layered FastAPI project with a SQLite database, running in your browser. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering