FastAPI Response Status Codes

HTTP status codes are part of the response, used to inform the client of the request processing result. FastAPI allows you to declare a default status code in the path operation decorator, and also to modify it dynamically within the function.

Declare status code

Usagestatus_codeThe parameter declares the response status code in the decorator:

Example

from fastapi import FastAPI, status

app = FastAPI()

# Use 201 status code when creating a resource
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
return {"name": name}

status_codeis a parameter of the decorator method (e.g.,@app.post()), not a parameter of the path operation function. It can be a number (such as201), can also usefastapi.statusconstants in (recommended, with editor autocomplete support).

HTTP Status Code Quick Reference

Scope	Category	Common status codes	Meaning
1xx	Information	--	rarely used directly
2xx	success	`200 OK`	Request successful (default status code)
		`201 Created`	Resource created successfully
		`204 No Content`	Successful but no content returned
3xx	Redirect	`304 Not Modified`	Resource not modified (cache valid)
4xx	Client error	`400 Bad Request`	Request format error
		`401 Unauthorized`	unauthenticated
		`403 Forbidden`	Authenticated but no permission
		`404 Not Found`	Resource not found
5xx	Server error	`500 Internal Server Error`	Server internal error

Using status constants

fastapi.statusprovides constants for all HTTP status codes, making it more convenient to use with editor auto-completion:

Example

from fastapi import FastAPI, status

app = FastAPI()

# POST - Create resource, returns 201
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
return {"name": name}

# DELETE - delete resource, returns 204 (no content)
@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
# Delete operations typically return no content
pass

# GET - Retrieve resource, returns 200 (default)
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}

204 No Contentindicates success but returns no content, suitable for delete operations. Note that a 204 response cannot contain a response body.

Common status code constants

Constants	Value	Use Case
`status.HTTP_200_OK`	200	GET request successful (default)
`status.HTTP_201_CREATED`	201	POST resource created successfully
`status.HTTP_204_NO_CONTENT`	204	DELETE successful, no content returned
`status.HTTP_400_BAD_REQUEST`	400	Request parameter error
`status.HTTP_401_UNAUTHORIZED`	401	Not logged in or token invalid
`status.HTTP_403_FORBIDDEN`	403	No permission to access
`status.HTTP_404_NOT_FOUND`	404	Resource not found
`status.HTTP_409_CONFLICT`	409	Resource conflict (e.g., duplicate creation)
`status.HTTP_422_UNPROCESSABLE_ENTITY`	422	Data validation failed
`status.HTTP_500_INTERNAL_SERVER_ERROR`	500	Server internal error

Summary

using decoratorsstatus_codeDeclaring default status code as a parameter
Recommendedfastapi.statusConstants, with editor autocomplete support
POST uses 201 for creating resources, DELETE uses 204 for deleting resources, GET uses 200 for retrieving resources.
4xx indicates client errors, 5xx indicates server errors

other extensions