Multiple Responses

Learn the fundamentals of multiple responses in FastAPI.

🎯 Core Concept

Endpoints often return different response types depending on success or failure conditions. FastAPI allows you to document multiple response models with different status codes, improving API clarity.

📖 What You'll Learn

In this section, you'll understand:

• Documenting multiple response types per endpoint

• Status code-specific response models

• Union types for multiple response shapes

• Success vs. error responses

• OpenAPI/Swagger documentation

💡 Simple Example

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Union

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str

class ErrorResponse(BaseModel):
    error: str

@app.get(
    "/items/{item_id}",
    response_model=Item,
    responses={
        200: {"model": Item},
        404: {"model": ErrorResponse}
    }
)
async def get_item(item_id: int):
    if item_id < 1:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"id": item_id, "name": "Widget"}

Union Response Types

@app.get("/search", response_model=Union[Item, List[Item]])
async def search(q: str):
    if q == "all":
        return [
            {"id": 1, "name": "Item 1"},
            {"id": 2, "name": "Item 2"}
        ]
    return {"id": 1, "name": "Item 1"}

Multiple Status Code Responses

from fastapi.responses import JSONResponse

@app.post(
    "/create",
    responses={
        201: {"model": Item},
        400: {"model": ErrorResponse},
        409: {"model": ErrorResponse}
    }
)
async def create_item(item: Item):
    if item.name == "":
        raise HTTPException(400, "Name required")
    return JSONResponse(
        status_code=201,
        content={"id": 1, "name": item.name}
    )

🔑 Key Takeaways

• ✅ Understand the purpose of multiple responses

• ✅ Know when to apply this pattern

• ✅ Recognize its benefits in real-world scenarios

• ✅ Be prepared to use it in your projects

Ready to explore more? Check out the advanced section for production patterns and edge cases.