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 <p>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
<p>app = FastAPI()</p><p>@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()
)</p><p>@app.exception_handler(Exception)
async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:</p><h1>生产环境建议只返回泛化错误，避免泄露敏感信息</h1><pre class="brush:php;toolbar:false;"><pre class="brush:php;toolbar:false;">return JSONResponse(
status_code=500,
content=ErrorResponse(
code=500,
message="Internal server error",
details=None
).model_dump()
)</code></pre>
定义并抛出自定义业务异常
为不同业务场景创建继承自 Exception 的异常类，并在视图中主动 raise。这样既能保持逻辑清晰，又可被统一处理器捕获：
class ValidationError(Exception):
def __init__(self, message: str, details: Optional[dict] = None):
self.message = message
self.details = details
self.status_code = 422
<h1>在路由中使用</h1><p>@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()
)</font><H3>让 OpenAPI 文档也反映统一错误结构</H3><p>默认情况下，FastAPI 不会自动把异常响应写入 OpenAPI schema。你可以通过 <code>responses</code> 参数显式声明，并复用 <code>ErrorResponse</code> 模型：</p><font color="gray"><pre class="brush:php;toolbar:false;"><code>@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"} 
