# 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:

```python
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

```http
GET /
```

* Returns HTTP **200 OK**
* Used as a health check

---

### Create User

```http
POST /create_user
```

* Returns HTTP **201 Created**
* Indicates successful resource creation

---

### Update User

```http
PUT /update_user/{target_name}
```

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

---

### Delete User

```http
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`

```python
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:**

```json
{
  "detail": "User not found"
}
```

---

## Example Requests

### Create User

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

### Update User

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

### Delete User

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

---

## Running the Application

Start the application using `uvicorn`:

```bash
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