fastapi可通过异常处理器与Pydantic模型统一错误响应格式为{“code”:int,”message”:str,”details”:Any}；需定义ErrorResponse模型、注册HTTPException/Exception/自定义异常处理器，并在路由中用responses参数声明OpenAPI错误结构。

FastAPI 中可以通过异常处理器（exception handlers）和 Pydantic 模型配合，实现所有错误响应都统一返回你定义的结构化错误格式，比如 {"code": 400, "message": "xxx", "details": {...}}。

定义统一错误响应模型

先用 Pydantic 创建一个标准错误响应模型，它将作为所有异常响应的序列化格式：

from pydantic import BaseModel from typing import Optional, Any 
class ErrorResponse(BaseModel): code: int message: str details: Optional[Any] = None

注册全局异常处理器

使用 app.add_exception_handler() 注册对 Exception 或具体异常（如 HTTPException、自定义异常）的处理逻辑。推荐按需注册两类：

• 处理 FastAPI 内置的 HTTPException：提取 status_code 和 detail
• 处理未捕获的通用异常（可选）：记录日志并返回 500 错误

from fastapi import FastAPI, HTTPException, Request from fastapi.responses import jsONResponse 
app = FastAPI()
@app.exception_handler(HTTPException) async def http_exception_handler(request: Request, exc: HTTPException) -> jsonResponse: return JSONResponse( status_code=exc.status_code, content=ErrorResponse( code=exc.status_code, message=exc.detail, details=getattr(exc, "headers", None) or getattr(exc, "data", None) ).model_dump() )
@app.exception_handler(Exception) async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
生产环境建议只返回泛化错误，避免泄露敏感信息
return JSONResponse(     status_code=500,     content=ErrorResponse(         code=500,         message="Internal server error",         details=None     ).model_dump() )


定义并抛出自定义业务异常
为不同业务场景创建继承自 Exception 的异常类，并在视图中主动 raise。这样既能保持逻辑清晰，又可被统一处理器捕获：
 

class ValidationError(Exception):     def __init__(self, message: str, details: Optional[dict] = None):         self.message = message         self.details = details         self.status_code = 422 
在路由中使用
@app.get("/items/{item_id}") def get_item(item_id: int): if item_id < 1: raise ValidationError("Item ID must be positive", {"field": "item_id"}) return {"id": item_id}

然后为其注册专属处理器（注意注册顺序：更具体的异常要先注册）：
 

@app.exception_handler(ValidationError) async def validation_error_handler(request: Request, exc: ValidationError) -> JSONResponse:     return JSONResponse(         status_code=exc.status_code,         content=ErrorResponse(             code=exc.status_code,             message=exc.message,             details=exc.details         ).model_dump()     )
让 OpenAPI 文档也反映统一错误结构
默认情况下，FastAPI 不会自动把异常响应写入 OpenAPI schema。你可以通过 responses 参数显式声明，并复用 ErrorResponse 模型：
@app.get(     "/users/{user_id}",     responses={         404: {"model": ErrorResponse, "description": "User not found"},         422: {"model": ErrorResponse, "description": "Validation failed"},     } ) def get_user(user_id: int):     if user_id != 123:         raise HTTPException(status_code=404, detail="User not found")     return {"name": "Alice"}

这样 Swagger ui 就会显示对应状态码的错误响应结构，提升 API 可用性与前端协作效率。