Raising HTTPException vs returning Response

[gsakkis]

I'm trying to understand the difference between raising an HTTPException vs returning a Response. Consider the following example:

from typing import Any

from litestar import Litestar, Response, get
from litestar.exceptions import HTTPException
from litestar.status_codes import HTTP_402_PAYMENT_REQUIRED
from pydantic import BaseModel


class Character(BaseModel):
    name: str
    nickname: str | None = None


the_dude = Character(name="Jeffrey Lebowski", nickname="The Dude")


@get("/response")
async def response(extra: bool = False) -> Response[dict[str, Any]]:
    return Response(
        status_code=HTTP_402_PAYMENT_REQUIRED,
        content=dict(
            status_code=HTTP_402_PAYMENT_REQUIRED,
            detail="Where's the money, Lebowski?",
            extra=the_dude if extra else {},
        ),
    )


@get("/exception")
async def exception(extra: bool = False) -> None:
    raise HTTPException(
        status_code=HTTP_402_PAYMENT_REQUIRED,
        detail="Where's the money, Lebowski?",
        extra=the_dude if extra else {},
    )


app = Litestar(route_handlers=[response, exception])

1. GET /response and GET /exception return the same status and body. In what case would you use the one or the other, or it's just a matter of style?
2. GET /response?extra=1 works, GET /exception?extra=1 raises SerializationException: Unsupported type: <class 'foo.Character'>. Is it deliberate that Response knows how to serialize Pydantic models and HTTPException doesn't? If yes why? If not I'd suggest this as a feature request.

[provinzkraut]

In what case would you use the one or the other, or it's just a matter of style?

In this example, they are functionally equivalent. The difference is mainly control flow. You can easily raise an HTTPException somewhere deep within a nested call you made from your route handler, and it will immediately abort the request. To do this with a regular Response, you'd have to explicitly pass that as a return type up the chain.

Is it deliberate that Response knows how to serialize Pydantic models and HTTPException doesn't?

It is, yes. Exceptions are intentionally more "low level" than responses, simply to avoid complexity and a whole catalogue of potential exception cases within those exceptions. The closer exceptions come to regular responses, the more can go wrong with them.

That being said, we could support this, but I'd argue that it should be opt-in, e.g. with a special ExceptionResponse that you can raise, but will go the same path as the regular responses. I'd like to see some use cases for this though before we go ahead and add this feature.

[gsakkis]

I'd like to see some use cases for this though before we go ahead and add this feature.

Well you mentioned a benefit of exceptions, aborting immediately the request instead of explicitly passing the response up the chain. This benefit stands regardless of whether extra holds "high level" data or not.

A counterargument could be that you can serialize the extra before passing it to the HTTPException. Which brings up a Pydantic question: is there an equivalent function of BaseModel.model_dump when the top level object is not a Pydantic model but a nested structure (say dict of lists of ...) that contains Pydantic models? I don't know of one (and I'd rather not write a custom one).

[provinzkraut]

This benefit stands regardless of whether extra holds "high level" data or not.

True, but so far I've never encountered a case where this would have been the best solution. Unless you're trying to abuse the exceptions as "early return responses", inside a non-error-case flow.

A counterargument could be that you can serialize the extra before passing it to the HTTPException

That doesn't really make a difference, since it's more likely to be subject to exceptions itself as well.

Which brings up a Pydantic question: is there an equivalent function of BaseModel.model_dump when the top level object is not a Pydantic model but a nested structure

litestar.serialization.encode_json can handle this.

[gsakkis]

Unless you're trying to abuse the exceptions as "early return responses", inside a non-error-case flow.

Not sure if it counts as abuse but it involves returning an error (or rather a list of errors) with detailed information for each one, something like this:

class InvalidEntriesException(ClientException):
    status_code = HTTP_422_UNPROCESSABLE_ENTITY

    def __init__(self, entries: list[InvalidEntry]) -> None:
        super().__init__(
            detail="Invalid entries",
            extra={"entries": [e.model_dump() for e in entries]},
        )

...

if invalid_entries:
    raise InvalidEntriesException(invalid_entries)