FastAPI: Set a Response's HTTP Status Code

Why it exists

APIs use HTTP status codes to communicate the result of an operation. While a 200 OK is a fine default for successful GET requests, other operations have more specific success codes. For example, creating a resource should ideally return 201 Created. FastAPI provides a declarative way to set the correct success code for an endpoint.

The mental model

Think of the success status code as part of the endpoint's contract, not the function's result. You declare it alongside the path and HTTP method in the decorator because it defines how the API behaves on success, independent of the specific data being returned by your function.

How it works

In any path operation decorator (@app.get, @app.post, etc.), add the status_code argument. FastAPI will use this code for all successful responses from that endpoint, overriding the default 200 OK. You can provide a raw integer like 201 or use Python's http.HTTPStatus enum for better readability (e.g., status_code=status.HTTP_201_CREATED after an import).

When to use it

Use this parameter whenever the default 200 OK is not the most semantically correct status for a successful operation. The most common use case is setting status_code=201 for POST requests that create a new resource. Another might be 204 No Content for a DELETE operation that succeeds but returns no body.

When not to use it

The status_code parameter is only for the default success response. For error conditions, you should raise an HTTPException. For instance, to return a 404 Not Found, you would raise HTTPException(status_code=404, detail="Item not found") from within your function logic. Do not try to set error codes in the decorator.

One canonical example

from fastapi import FastAPI, status

app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED)

async def create_item(name: str):

Logic to create the item in a database...

return {"name": name}

A successful POST to /items/ will now return a 201 status code.