FastAPI中统一错误响应需结合自定义异常类、@app.exception_handler()装饰器和Pydantic模型。先定义ErrorResponse模型，再创建继承Exception的APIException类，接着注册全局处理器返回JSONResponse，最后在路由中raise实例即可输出标准化错误。
FastAPI 中让错误响应统一使用自定义异常模型，核心是结合
类、
装饰器和 Pydantic 模型三者完成标准化输出。
定义统一的错误响应模型
先用 Pydantic 创建一个结构清晰的错误响应模型，例如包含
状态码
、错误码、消息和可选详情：
创建自定义异常类
继承 Python 的
，并携带必要字段（如
、
、
），方便后续
处理器
提取：
注册全局异常处理器
使用
拦截所有该类型异常，并返回符合
模型的 JSON 响应：
注意：这个处理器只捕获
及其子类。若需统一处理所有未捕获异常（如 422 验证错误），可额外注册
或通用
处理器，但建议保持语义明确，避免掩盖开发问题。
在
路由
中主动抛出自定义异常
直接 raise 实例即可，FastAPI 会自动交由对应 handler 处理：
php版微信js-sdk支付接口类
php版微信js-sdk支付接口类
下载
此时响应体为标准 JSON：
状态码也正确设为 400。
进阶：支持多种错误类型（可选）
可定义不同业务异常子类，复用同一 handler：
这样既保持统一格式，又提升
代码可读性
和维护性。
Exception@app.exception_handler()from pydantic import BaseModel
from typing import Optional
class ErrorResponse(BaseModel):
code: int
message: str
detail: Optional[str] = None
Exceptionstatus_codecodemessageclass APIException(Exception):
def __init__(self, status_code: int, code: int, message: str, detail: str = None):
self.status_code = status_code
self.code = code
self.message = message
self.detail = detail@app.exception_handler(APIException)ErrorResponsefrom fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
@app.exception_handler(APIException)
async def api_exception_handler(request: Request, exc: APIException):
return JSONResponse(
status_code=exc.status_code,
content=ErrorResponse(
code=exc.code,
message=exc.message,
detail=exc.detail
).dict()
)
APIExceptionRequestValidationErrorException@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id < 1:
raise APIException(
status_code=400,
code=1001,
message="无效的 item ID",
detail="item_id 必须大于 0"
)
return {"id": item_id}{
"code": 1001,
"message": "无效的 item ID",
"detail": "item_id 必须大于 0"
}class NotFoundException(APIException):
def __init__(self, resource: str):
super().__init__(
status_code=404,
code=2001,
message=f"{resource} 不存在"
)
使用时
raise NotFoundException("用户")