openai/openai-python · error · ValueError

Subclasses of HTTP response classes cannot be passed to `cas

Error message

Subclasses of HTTP response classes cannot be passed to `cast_to`

What it means

The SDK only returns its own exact httpx.Response class when cast_to is an HTTP response type. Because the ResponseT TypeVar is invariant, passing a subclass of httpx.Response to cast_to cannot be safely supported, so it is explicitly rejected.

Source

Thrown at src/openai/_legacy_response.py:286

            return cast(R, response.text.lower() == "true")

        if inspect.isclass(origin) and issubclass(origin, HttpxBinaryResponseContent):
            return cast(R, cast_to(response))  # type: ignore

        if origin == LegacyAPIResponse:
            raise RuntimeError("Unexpected state - cast_to is `APIResponse`")

        response_types = http_response_types()
        if inspect.isclass(
            origin  # pyright: ignore[reportUnknownArgumentType]
        ) and issubclass(origin, response_types):
            # Because of the invariance of our ResponseT TypeVar, users can subclass httpx.Response
            # and pass that class to our request functions. We cannot change the variance to be either
            # covariant or contravariant as that makes our usage of ResponseT illegal. We could construct
            # the response class ourselves but that is something that should be supported directly in httpx
            # as it would be easy to incorrectly construct the Response object due to the multitude of arguments.
            if cast_to not in response_types:
                raise ValueError("Subclasses of HTTP response classes cannot be passed to `cast_to`")
            return cast(R, response)

        if (
            inspect.isclass(
                origin  # pyright: ignore[reportUnknownArgumentType]
            )
            and not issubclass(origin, BaseModel)
            and issubclass(origin, pydantic.BaseModel)
        ):
            raise TypeError("Pydantic models must subclass our base model type, e.g. `from openai import BaseModel`")

        if (
            cast_to is not object
            and not origin is list
            and not origin is dict
            and not origin is Union
            and not issubclass(origin, BaseModel)
        ):

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Use cast_to=httpx.Response (the exact class) and access extra data via response.headers or the parsed body
2. Wrap or post-process the returned httpx.Response in your own container class after the call instead of subclassing

Example fix

# before
resp = client.post('/models', cast_to=MyHttpResponse, ...)
# after
resp = client.post('/models', cast_to=httpx.Response, ...)
headers = resp.headers

import httpx
assert cast_to is httpx.Response or not (isinstance(cast_to, type) and issubclass(cast_to, httpx.Response) and cast_to is not httpx.Response)

def is_safe_cast_to(t: object) -> bool:
    import httpx
    return t is httpx.Response or not (isinstance(t, type) and issubclass(t, httpx.Response))

When it happens

Trigger: Calling an API method (or using with_raw_response) with cast_to set to a class that subclasses httpx.Response but is not exactly httpx.Response, e.g. cast_to=MyResponse where MyResponse(httpx.Response).

Common situations: Developers wanting extra convenience fields on the raw response and subclassing httpx.Response; migrating code from hand-written httpx calls that used custom response classes.

Related errors

• Subclasses of HTTP response classes cannot be passed to `cas
• Pydantic models must subclass our base model type, e.g. `fro
• Unsupported type, expected {cast_to} to be a subclass of {Ba
• Pydantic models must subclass our base model type, e.g. `fro
• Unsupported type, expected {cast_to} to be a subclass of {Ba

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/f988b8f697a051e3. Report an issue: GitHub.