Response Status Code

Learn how to set HTTP status codes in FastAPI using the status_code parameter and status module

HTTP status codes communicate the result of a request. FastAPI makes it easy to set appropriate status codes for your API responses.

Setting Status Code

Use the status_code parameter in your path operation decorator:

from fastapi import FastAPI

app = FastAPI()

@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

The status_code parameter:

• Sets the HTTP status code in the response
• Documents it in the OpenAPI schema
• Validates that it’s a valid HTTP status code

Using the status Module

Instead of memorizing numeric codes, use FastAPI’s status module:

from fastapi import FastAPI, status

app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
    return None

@app.get("/items/", status_code=status.HTTP_200_OK)
async def read_items():
    return [{"name": "Foo"}, {"name": "Bar"}]

Using status.HTTP_* constants makes your code more readable and helps avoid typos.

Common Status Codes

Success Codes (2xx)

200 OK (Default)

@app.get("/items/", status_code=status.HTTP_200_OK)
async def read_items():
    return [{"name": "Foo"}]
# Default for GET, no need to specify

Redirection Codes (3xx)

from fastapi import FastAPI, status
from fastapi.responses import RedirectResponse

app = FastAPI()

@app.get("/old-path", status_code=status.HTTP_301_MOVED_PERMANENTLY)
async def redirect_old_path():
    return RedirectResponse(url="/new-path")

@app.get("/temporary", status_code=status.HTTP_307_TEMPORARY_REDIRECT)
async def temporary_redirect():
    return RedirectResponse(url="/other-path")

Client Error Codes (4xx)

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

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

@app.post("/items/")
async def create_item(item: Item):
    if item.price < 0:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Price cannot be negative"
        )
    return item

Server Error Codes (5xx)

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

@app.get("/items/")
async def read_items():
    try:
        # Some database operation
        items = get_items_from_db()
        return items
    except DatabaseError:
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Database temporarily unavailable"
        )

Status Code Reference

2xx Success

1. 200 OK

   Default success response (GET, PUT, PATCH)

2. 201 Created

   Resource successfully created (POST)

3. 202 Accepted

   Request accepted but processing not complete

4. 204 No Content

   Success with no response body (DELETE)

3xx Redirection

• 301 Moved Permanently: Resource permanently moved
• 302 Found: Temporary redirect (legacy)
• 307 Temporary Redirect: Temporary redirect (preserves method)
• 308 Permanent Redirect: Permanent redirect (preserves method)

4xx Client Errors

• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource doesn’t exist
• 422 Unprocessable Entity: Validation error
• 429 Too Many Requests: Rate limit exceeded

5xx Server Errors

• 500 Internal Server Error: Unexpected server error
• 502 Bad Gateway: Invalid upstream response
• 503 Service Unavailable: Service temporarily down
• 504 Gateway Timeout: Upstream timeout

Dynamic Status Codes

Change status codes dynamically using Response:

from fastapi import FastAPI, Response, status

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, response: Response):
    if item_id in items_db:
        # Update existing item
        items_db[item_id] = item
        response.status_code = status.HTTP_200_OK
        return item
    else:
        # Create new item
        items_db[item_id] = item
        response.status_code = status.HTTP_201_CREATED
        return item

When using Response to set status codes dynamically, the code set in the decorator becomes the default shown in docs.

Status Codes with HTTPException

Raise exceptions with specific status codes:

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

items_db = {"foo": "The Foo Item"}

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Item {item_id} not found",
            headers={"X-Error": "Item not found"},
        )
    return {"item": items_db[item_id]}

@app.post("/items/")
async def create_item(item: Item):
    if item.id in items_db:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=f"Item {item.id} already exists"
        )
    items_db[item.id] = item
    return item

Best Practices

Good: Semantic Status Codes

@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item

@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
    return None

Always use appropriate status codes:

• POST for creation → 201 Created
• DELETE with no body → 204 No Content
• GET/PUT success → 200 OK
• Errors → Appropriate 4xx or 5xx code

Status Code Guidelines

Method	Success Code	Typical Use
GET	200	Resource retrieval
POST	201	Resource creation
PUT	200	Full update
PATCH	200	Partial update
DELETE	204	Deletion (no body)
DELETE	200	Deletion (with body)

Testing Status Codes

from fastapi.testclient import TestClient
from fastapi import status

def test_create_item():
    response = client.post("/items/", json={"name": "Foo"})
    assert response.status_code == status.HTTP_201_CREATED

def test_item_not_found():
    response = client.get("/items/999")
    assert response.status_code == status.HTTP_404_NOT_FOUND

def test_delete_item():
    response = client.delete("/items/1")
    assert response.status_code == status.HTTP_204_NO_CONTENT

Related Topics

• Response Model - Define response schemas
• Extra Models - Work with multiple models
• Request Body - Handle request data