FastAPI：运行时/验证错误响应设置及异常响应添加自定义头

问题1：运行时或验证错误的响应错误设置 #

• 直接抛出HTTPException：这是最常用的方式，可指定状态码、错误信息和自定义响应头，示例中/fail端点的用法就是典型场景。
• 自定义全局异常处理器：针对未捕获的异常，使用@app.exception_handler()装饰器注册处理器，能统一处理特定异常（如ValidationError、通用Exception），按需构建响应格式。
• 处理验证错误：FastAPI默认对参数验证失败返回422 Unprocessable Entity响应，若需自定义格式，可注册ValidationError的专属异常处理器，重新生成响应内容。

问题2：未捕获运行时异常时添加自定义响应头 #

未捕获的运行时异常（如NotImplementedError）会触发FastAPI默认异常处理流程，此前设置的response.headers会被重置。解决思路是注册全局异常处理器，在不修改原异常响应内容的前提下，为响应添加自定义头：

修改后的完整代码 #

from fastapi import FastAPI, HTTPException, Response, Request
import uvicorn

app = FastAPI()

# 全局异常处理器：捕获所有未处理的Exception
@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    # 获取FastAPI默认生成的异常响应，保留原内容和格式
    default_response = await app.default_exception_handler(request, exc)
    # 添加自定义响应头
    default_response.headers['myheader'] = '123456'
    return default_response

# 可选：单独捕获特定异常（如NotImplementedError），优先级高于通用Exception处理器
# @app.exception_handler(NotImplementedError)
# async def not_implemented_handler(request: Request, exc: NotImplementedError):
#     default_response = await app.default_exception_handler(request, exc)
#     default_response.headers['myheader'] = '123456'
#     return default_response

@app.get("/ok", include_in_schema=True)
def a(response: Response):
    response.headers['myheader'] = '123456'
    return {"status": "OK"}

@app.get("/fail", include_in_schema=True)
def b(response: Response):
    raise HTTPException(401, 'Error', headers={'myheader': '123456'})

@app.get("/nok", include_in_schema=True)
def c(response: Response):
    raise NotImplementedError("Let's see a header")

uvicorn.run(app=app, host="0.0.0.0", port=9999)

原理说明 #

• 全局异常处理器拦截未捕获异常后，先调用FastAPI内置的default_exception_handler获取原响应，确保异常信息、状态码、响应格式完全不变。
• 仅在原响应基础上追加自定义响应头，完全符合“不修改响应内容及异常信息”的要求。
• 若只需针对特定异常处理，可注册对应异常的专属处理器，其优先级高于通用的Exception处理器。

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