How do you set status codes and headers?

Question

Accepted Answer

FastAPI returns `200 OK` by default, but you control the **status code** (via the decorator or the response object) and **headers** when you need different behavior — important for proper REST semantics.

## Setting a default status code on the route

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 201 for resource creation
def create_item(item: Item):
    return item                                             # returns with 201

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)  # 204
def delete_item(id: int):
    ...
```

The `status_code` decorator parameter sets the default success status. Using the `status` constants (e.g. `status.HTTP_201_CREATED`) is clearer than magic numbers. Correct codes matter: `201` for created, `204` for no content, etc.

## Dynamic status codes and headers via the Response object

```python
from fastapi import Response

@app.get("/items/{id}")
def get_item(id: int, response: Response):
    item = db.get(id)
    if not item:
        response.status_code = status.HTTP_404_NOT_FOUND   # set dynamically
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # set a custom header
    return item
```

Injecting a `Response` parameter lets you set the status code and headers **conditionally** at runtime.

## Errors: raise HTTPException

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found",
                            headers={"X-Error": "NotFound"})   # status + detail + headers
    return item
```

For error responses, `raise HTTPException(...)` is the idiomatic way — it sets the status, a JSON `detail` message, and optional headers.

## Returning a custom Response directly

```python
from fastapi.responses import JSONResponse
return JSONResponse(content={...}, status_code=202, headers={"X-Custom": "v"})
```

## Why it matters

Proper status codes and headers are essential for building correct, well-behaved REST APIs — clients and tools rely on standard HTTP semantics (201 for created, 404 for not found, 204 for no content, etc.), so returning the right code is part of a quality API contract.

FastAPI gives you clean control: a default `status_code` on the route for the common case, the injectable `Response` object for dynamic codes/headers, and `HTTPException` as the idiomatic way to signal errors with the appropriate status and a JSON detail.

Understanding these mechanisms — and using the `status` constants for clarity — is everyday knowledge for building APIs that behave correctly and communicate clearly with their consumers.