status

HTTP status code constants for use in FastAPI applications.

status

A module containing HTTP status code constants. These constants make your code more readable and maintainable by using descriptive names instead of numeric codes.

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

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

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

Common Status Codes

Success (2xx)

HTTP_200_OK · int · default: "200"

Standard response for successful HTTP requests.

HTTP_201_CREATED · int · default: "201"

The request has been fulfilled and a new resource has been created.

HTTP_202_ACCEPTED · int · default: "202"

The request has been accepted for processing, but processing has not been completed.

HTTP_204_NO_CONTENT · int · default: "204"

The server successfully processed the request, but is not returning any content.

Redirection (3xx)

HTTP_301_MOVED_PERMANENTLY · int · default: "301"

The resource has been moved permanently to a new URL.

HTTP_302_FOUND · int · default: "302"

The resource temporarily resides under a different URL.

HTTP_304_NOT_MODIFIED · int · default: "304"

The resource has not been modified since the last request.

HTTP_307_TEMPORARY_REDIRECT · int · default: "307"

The request should be repeated with another URI, but future requests should use the original URI.

Client Errors (4xx)

HTTP_400_BAD_REQUEST · int · default: "400"

The server cannot process the request due to a client error (e.g., malformed syntax).

HTTP_401_UNAUTHORIZED · int · default: "401"

Authentication is required and has failed or has not been provided.

HTTP_403_FORBIDDEN · int · default: "403"

The server understood the request but refuses to authorize it.

HTTP_404_NOT_FOUND · int · default: "404"

The requested resource could not be found.

HTTP_405_METHOD_NOT_ALLOWED · int · default: "405"

The method specified in the request is not allowed for the resource.

HTTP_409_CONFLICT · int · default: "409"

The request could not be completed due to a conflict with the current state of the resource.

HTTP_422_UNPROCESSABLE_ENTITY · int · default: "422"

The request was well-formed but contains semantic errors (commonly used for validation errors).

HTTP_429_TOO_MANY_REQUESTS · int · default: "429"

The user has sent too many requests in a given amount of time (rate limiting).

Server Errors (5xx)

HTTP_500_INTERNAL_SERVER_ERROR · int · default: "500"

A generic error message when the server encounters an unexpected condition.

HTTP_502_BAD_GATEWAY · int · default: "502"

The server received an invalid response from an upstream server.

HTTP_503_SERVICE_UNAVAILABLE · int · default: "503"

The server is currently unable to handle the request (temporarily overloaded or down for maintenance).

HTTP_504_GATEWAY_TIMEOUT · int · default: "504"

The server did not receive a timely response from an upstream server.

WebSocket Status Codes

WS_1000_NORMAL_CLOSURE · int · default: "1000"

Normal closure; the connection successfully completed.

WS_1001_GOING_AWAY · int · default: "1001"

The endpoint is going away (e.g., server shutdown or browser navigation).

WS_1003_UNSUPPORTED_DATA · int · default: "1003"

The endpoint received data of a type it cannot accept.

WS_1008_POLICY_VIOLATION · int · default: "1008"

The connection was closed because an endpoint received a message that violated its policy.

Usage Examples

Setting Response Status Code

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

Raising Exceptions

from fastapi import HTTPException, status

if not user.is_authenticated:
    raise HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Not authenticated",
        headers={"WWW-Authenticate": "Bearer"},
    )

Conditional Status Codes

from fastapi import Response, status

@app.delete("/items/{item_id}")
def delete_item(item_id: int, response: Response):
    if item_id in items:
        del items[item_id]
        response.status_code = status.HTTP_204_NO_CONTENT
    else:
        response.status_code = status.HTTP_404_NOT_FOUND
    return {"ok": True}

Usage Notes

• Using named constants improves code readability
• Makes it easier to understand the intent of status codes at a glance
• Reduces errors from typos in numeric codes
• All standard HTTP status codes are available
• WebSocket status codes are also included with the WS_ prefix
• These constants are re-exported from Starlette

Learn More

Read more in the FastAPI docs for Response Status Code.