python-doc/Docs/Libs/FastAPI/08.Status-Codes.md

FastAPI – HTTP Status Codes and Error Handling

This document demonstrates how to use HTTP status codes in FastAPI to accurately represent the result of an API operation. Correct status codes improve API reliability, observability, and client-side behavior.

---

Example Application

Create or update main.py with the following content:

from fastapi import FastAPI, status, HTTPException

app = FastAPI()

users = [
    {"name": "abbas", "age": 20},
    {"name": "mmd", "age": 37},
    {"name": "asghar", "age": 19},
]


@app.get("/", status_code=status.HTTP_200_OK)
def home_page():
    return {"msg": "API is working"}


@app.get("/users", status_code=status.HTTP_200_OK)
def show_users():
    return users


@app.post("/create_user", status_code=status.HTTP_201_CREATED)
def create_user(name: str, age: int):
    new_user = {"name": name, "age": age}
    users.append(new_user)
    return {"msg": f"user {name} with age {age} created"}


@app.put("/update_user/{target_name}", status_code=status.HTTP_202_ACCEPTED)
def update_user(target_name: str, age: int):
    for user in users:
        if user["name"] == target_name:
            user["age"] = age
            return {"msg": f"user {target_name} updated"}
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="User not found"
    )


@app.delete("/delete_user/{target_name}", status_code=status.HTTP_204_NO_CONTENT)
def delete_user(target_name: str):
    for user in users:
        if user["name"] == target_name:
            users.remove(user)
            return
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="User not found"
    )

---

Status Code Overview

HTTP status codes communicate the result of an API request to clients and monitoring systems.

Code	Meaning	Usage
200	OK	Successful GET requests
201	Created	Resource successfully created
202	Accepted	Update request accepted
204	No Content	Resource deleted successfully
404	Not Found	Requested resource does not exist

---

Endpoint Behavior

Root Endpoint

GET /

• Returns HTTP 200 OK
• Used as a health check

---

Create User

POST /create_user

• Returns HTTP 201 Created
• Indicates successful resource creation

---

Update User

PUT /update_user/{target_name}

• Returns HTTP 202 Accepted on success
• Raises HTTP 404 Not Found if user does not exist

---

Delete User

DELETE /delete_user/{target_name}

• Returns HTTP 204 No Content on success
• Returns no response body
• Raises HTTP 404 Not Found if user does not exist

---

Error Handling with HTTPException

raise HTTPException(
    status_code=status.HTTP_404_NOT_FOUND,
    detail="User not found"
)

• Immediately stops request processing
• Returns structured error responses
• Automatically serialized by FastAPI

Error Response Example:

{
  "detail": "User not found"
}

---

Example Requests

Create User

curl -X POST "http://localhost:8000/create_user?name=ali&age=25"

Update User

curl -X PUT "http://localhost:8000/update_user/ali?age=30"

Delete User

curl -X DELETE "http://localhost:8000/delete_user/ali"

---

Running the Application

Start the application using uvicorn:

uvicorn main:app --reload

---

Best Practices

• Always return meaningful HTTP status codes
• Use status module instead of hard-coded numbers
• Use HTTPException for predictable error handling
• Do not return response bodies with 204 No Content
• Align status codes with REST conventions
• Ensure monitoring systems rely on status codes, not messages
• Standardize error formats across services