FastAPI Response Status Code

正確地回傳 HTTP 狀態碼是 Web API 開發的基本功。它能讓客戶端（前端、App 或其他服務）快速理解請求的執行結果。

在裝飾器中設定預設狀態碼

最常見的做法是在路徑操作裝飾器中，使用 status_code 參數設定成功時的預設狀態碼。

from fastapi import FastAPI

app = FastAPI()

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

當請求成功時，FastAPI 會自動回傳 201 Created 狀態碼。

使用 FastAPI 的 Status 常數

直接寫數字 (如 201, 404) 也可以，但建議使用 FastAPI 提供的 status 常數，這能增加程式碼的可讀性，也避免打錯字。

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}

常用的狀態碼常數包括：

status.HTTP_200_OK: 成功。
status.HTTP_201_CREATED: 資源已建立。
status.HTTP_204_NO_CONTENT: 成功但無內容（常配合 delete）。
status.HTTP_400_BAD_REQUEST: 用戶端的請求錯誤。
status.HTTP_401_UNAUTHORIZED: 未授權。
status.HTTP_403_FORBIDDEN: 禁止存取。
status.HTTP_404_NOT_FOUND: 找不到資源。

動態修改狀態碼

有時候你需要根據邏輯動態地決定回傳什麼狀態碼，這時可以透過 Response 物件來達成。

from fastapi import FastAPI, Response, status

app = FastAPI()

@app.post("/tasks/")
async def create_task(name: str, response: Response):
    if name == "special":
        # 動態設定為 202 Accepted
        response.status_code = status.HTTP_202_ACCEPTED
        return {"message": "Processing later"}

    # 預設維持 200 OK
    return {"message": "Task created"}

如果你想回傳「錯誤」狀態碼（如 400 或 404），建議直接使用 raise HTTPException，這在邏輯上更清晰。

總結

在 @app.get / @app.post 裝飾器中使用 status_code 設定預設成功狀態碼。
推薦使用 from fastapi import status 來取得語意化常數。
如果需要動態調整，可以在函數參數中宣告 response: Response。