How to Set Status Code in FastAPI: Simple Guide

In FastAPI, you can set the HTTP status code by using the status_code parameter in your path operation decorator or by returning a Response object with a specific status code. This controls what status code the client receives when calling your API endpoint.

Syntax

FastAPI lets you set the status code in two main ways:

• Use the status_code parameter in the route decorator to set a fixed status code for the response.
• Return a Response or its subclass with a custom status_code to set it dynamically.

This controls the HTTP status code sent back to the client.

python

from fastapi import FastAPI, Response, status

app = FastAPI()

@app.get("/fixed-status", status_code=status.HTTP_201_CREATED)
def fixed_status():
    return {"message": "Created with fixed status code"}

@app.get("/dynamic-status")
def dynamic_status():
    return Response(content="Custom status code", status_code=status.HTTP_202_ACCEPTED)

Example

This example shows two endpoints: one sets a fixed status code using the status_code parameter, and the other returns a Response with a custom status code.

python

from fastapi import FastAPI, Response, status

app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item(item: dict):
    return {"item": item, "message": "Item created"}

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    # Simulate deletion
    return Response(content=f"Item {item_id} deleted", status_code=status.HTTP_204_NO_CONTENT)

Output

POST /items/ responds with status 201 Created
DELETE /items/123 responds with status 204 No Content

Common Pitfalls

Common mistakes when setting status codes in FastAPI include:

• Not using the status_code parameter in the decorator, which defaults to 200 OK.
• Returning a dictionary or model without setting status_code, so the status code stays 200.
• Using Response but forgetting to set content or returning incompatible types.

Always ensure the status code matches the action's meaning (e.g., 201 for creation, 204 for no content).

python

from fastapi import FastAPI

app = FastAPI()

# Wrong: status code defaults to 200
@app.post("/wrong")
def wrong():
    return {"message": "Created but status is 200"}

# Right: set status_code to 201
@app.post("/right", status_code=201)
def right():
    return {"message": "Created with status 201"}

Quick Reference

Here is a quick summary of how to set status codes in FastAPI:

Method	How to Set Status Code	Example
Fixed status code	Use status_code parameter in route decorator	@app.post("/", status_code=201)
Dynamic status code	Return Response with status_code	return Response(status_code=204)
Use constants	Use fastapi.status constants for clarity	status.HTTP_201_CREATED

Key Takeaways

Use the status_code parameter in the route decorator to set a fixed HTTP status code.

Return a Response object with a status_code to set it dynamically.

Use status code constants from fastapi.status for readable code.

Remember to match status codes to the action meaning (e.g., 201 for creation).

Without setting status_code, FastAPI defaults to 200 OK.