Desired usage of the `ErrorResponse` Pydantic data model?

[TUdby]

Every path endpoint is documenting error responses like 404 and 422 as returning a custom ErrorResponse pydantic model, and the path funcs type hint it as a return value. I'm not entirely sure how it's supposed to be used and why. From the fastapi docs docs error handling is usually with HTTPException, like this

from fastapi import HTTPException

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")

but I also see in the docs a return value pattern, which seems to get closer to what's in this repo

@app.get("/items/{item_id}", response_model=Item, responses={404: {"model": Message}})
async def read_item(item_id: str):
    if item_id == "foo":
        return {"id": "foo", "value": "there goes my hero"}
    return JSONResponse(status_code=404, content={"message": "Item not found"})

So is the intended pattern this? (here's using an example from the repo)

@router.post(
    "/agents/search",
    response_model=AgentsSearchPostResponse,
    responses={"404": {"model": ErrorResponse}, "422": {"model": ErrorResponse}},
    tags=["Agents"],
)
def search_agents(
    body: AgentsSearchPostRequest,
) -> Union[AgentsSearchPostResponse, ErrorResponse]:
    ...
    if not agents:
        return JSONResponse(status_code=404, content=ErrorResponse(code='404', message='agent not found').model_dump())

There's a few things that feel off with that. First, we're reporting the error code twice. Second, with the pydantic validation a 422 malformed input is caught before the function is entered, and there's no custom error handler in this repo to deal with that, so the standard starlette handling is already violating the declared data model, meaning that the OpenAPI spec here is already not valid out of the box. Third, the response value pattern is preferred less than the HTTPException pattern as the HTTPException could be raised from anywhere and cut off all further action, while creating responses for error codes can require more finesse in complex applications.

What is the intended pattern?