FastAPI Backend Development Bootcamp · Lesson

Response Models & Status Codes

Learn to define explicit response models and set appropriate HTTP status codes for various API operations.

Response Models & Status Codes is a free FastAPI Backend Development Bootcamp lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the FastAPI Backend Development Bootcamp learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

API Responses: The Basics

When you make a request to an API, the server sends back a response. This response isn't just data; it also includes important information about the request's outcome.

FastAPI makes it easy to return data, usually as JSON. But we can make our APIs even better by being explicit about what data to expect and what happened.

Why Use Response Models?

Response models define the exact structure of the data your API will send back. This is crucial for several reasons:

Data Consistency: Ensures your API always returns data in a predictable format.
Automatic Docs: FastAPI automatically generates OpenAPI documentation showing the expected response structure.
Data Validation: FastAPI can validate the outgoing data against your model, catching errors before sending.

Defining a Simple Response Model

We use Pydantic models to define response structures. Then, we tell FastAPI which model to use with the response_model parameter in our endpoint decorator.

Try running this example and check the /docs endpoint!

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Product(BaseModel):
    name: str
    price: float
    is_available: bool = True

@app.get("/products/single", response_model=Product)
def get_single_product():
    return {"name": "Coffee Mug", "price": 9.99, "is_available": True}

# To run: uvicorn main:app --reload

Returning Lists with Response Models

What if your endpoint returns a list of items? You can specify this in your response_model by using Python's List type from the typing module.

This tells FastAPI to expect a list where each item matches your Pydantic model.

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

app = FastAPI()

class Book(BaseModel):
    title: str
    author: str

@app.get("/books", response_model=List[Book])
def get_all_books():
    return [
        {"title": "The Hobbit", "author": "J.R.R. Tolkien"},
        {"title": "1984", "author": "George Orwell"}
    ]

# To run: uvicorn main:app --reload

Understanding HTTP Status Codes

Beyond the data, every API response includes an HTTP Status Code. This three-digit number tells the client about the outcome of their request.

2xx Success: Request was successfully received, understood, and accepted. (e.g., 200 OK, 201 Created)
4xx Client Error: The client made an error. (e.g., 400 Bad Request, 404 Not Found)
5xx Server Error: The server failed to fulfill an apparently valid request. (e.g., 500 Internal Server Error)

FastAPI's Default Status Codes

FastAPI automatically assigns default status codes based on the HTTP method:

GET: 200 OK
POST: 200 OK (but often 201 Created is better)
PUT/DELETE: 200 OK

While these defaults work, explicitly setting status codes makes your API more precise and user-friendly.

Setting Custom Success Codes (201)

For operations that create a new resource (like a POST request), returning a 201 Created status code is best practice. You can specify this directly in your path operation decorator.

Run this and observe the network response code!

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()

class NewItem(BaseModel):
    name: str
    description: str | None = None

@app.post("/items", status_code=status.HTTP_201_CREATED)
def create_item(item: NewItem):
    # Imagine saving 'item' to a database here
    return {"message": "Item created successfully", "item": item}

# To run: uvicorn main:app --reload

Handling Errors with HTTPException (404)

When a requested resource isn't found, you should return a 404 Not Found status. FastAPI provides HTTPException to raise these errors easily.

This stops execution and returns a standard JSON error response.

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

fake_items_db = {"foo": {"name": "Foo"}, "bar": {"name": "Bar"}}

@app.get("/items/{item_id}")
def read_item(item_id: str):
    if item_id not in fake_items_db:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Item not found")
    return fake_items_db[item_id]

# To run: uvicorn main:app --reload

Combining Models & Status Codes

You'll often use both response models and custom status codes together. For example, a successful update might return a 200 OK with the updated resource, while a failed update might return a 400 Bad Request.

This creates robust and predictable API behavior.

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()

class UserOut(BaseModel):
    id: int
    username: str

@app.put("/users/{user_id}", response_model=UserOut, status_code=status.HTTP_200_OK)
def update_user(user_id: int, new_username: str):
    # Imagine updating user in DB
    if user_id == 1:
        return {"id": user_id, "username": new_username}
    return {"id": user_id, "username": "default_user"}

# To run: uvicorn main:app --reload

Quick Check: Status Codes

A client sends a POST request to create a new user. The server successfully processes the request and saves the user data. Which HTTP status code is the most appropriate to return?

Recap: Clear Responses

In this lesson, you learned how to make your FastAPI responses clear and predictable. We covered:

Defining response models with Pydantic for consistent data and automatic documentation.
Understanding and explicitly setting HTTP status codes like 201 Created or handling errors with HTTPException for 404 Not Found.

These practices greatly improve the usability and robustness of your API.

Frequently asked questions

Is the “Response Models & Status Codes” lesson free?

Yes — the full text of “Response Models & Status Codes” is free to read here on the web, and the FastAPI Backend Development Bootcamp course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the FastAPI Backend Development Bootcamp course, upgrade to CoddyKit PRO.

What will I learn in “Response Models & Status Codes”?

Learn to define explicit response models and set appropriate HTTP status codes for various API operations. You practise FastAPI Backend Development Bootcamp with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start FastAPI Backend Development Bootcamp?

No prior experience is required. FastAPI Backend Development Bootcamp on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Response Models & Status Codes” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this FastAPI Backend Development Bootcamp lesson?

Yes. Every FastAPI Backend Development Bootcamp lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to FastAPI Backend Development Bootcamp