FastAPI中使用Postman测试时自定义状态码替代500内部错误的方法

方案1：主动抛出HTTPException（适用单接口自定义错误） #

这是最简便的实现方式，适合在业务逻辑判断触发错误时，直接返回指定状态码和响应内容：

• 第一步导入FastAPI内置的HTTPException
• 第二步在路由函数中，触发错误条件时抛出异常，指定status_code和返回内容detail

代码示例：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class ReqData(BaseModel):
    num: int

@app.post("/test")
def test_post(data: ReqData):
    # 自定义错误判断逻辑
    if data.num < 0:
        # 抛出400状态码，自定义返回内容
        raise HTTPException(status_code=400, detail="输入数值不能为负数")
    if data.num > 100:
        # 抛出403状态码，自定义返回内容
        raise HTTPException(status_code=403, detail="输入数值超出最大限制100")
    return {"code": 200, "msg": "success", "data": data.num}

抛出异常后FastAPI会自动组装响应，不会返回默认的500错误。

方案2：全局异常处理器（适用统一处理同类型错误） #

如果你需要全局捕获某一类错误（比如自定义业务异常、Python内置的ValueError/TypeError等），统一返回指定的状态码和响应，可以用全局异常注册实现：
代码示例：

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from pydantic import BaseModel

app = FastAPI()

# 自定义业务异常类
class BizError(Exception):
    def __init__(self, code: int, msg: str):
        self.code = code
        self.msg = msg

# 注册自定义业务异常的全局处理器
@app.exception_handler(BizError)
async def biz_error_handler(request: Request, exc: BizError):
    return JSONResponse(
        status_code=exc.code,
        content={"code": exc.code, "msg": exc.msg}
    )

# 也可以捕获Python内置异常，比如ValueError
@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content={"code": 400, "msg": f"参数错误：{str(exc)}"}
    )

class ReqData(BaseModel):
    num: int

@app.post("/test")
def test_post(data: ReqData):
    if data.num < 0:
        # 抛出自定义业务异常，全局处理器会自动处理
        raise BizError(code=400, msg="输入数值不能为负数")
    # 触发内置ValueError也会被全局捕获
    if data.num == 999:
        raise ValueError("无效的特殊数值")
    return {"code": 200, "msg": "success", "data": data.num}

验证方式 #

在Postman中构造对应的错误输入参数发送请求，即可看到返回的状态码和响应内容都是你自定义的内容，不会再返回默认的500 Internal Server Error。

内容的提问来源于stack exchange，提问作者mufassir