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's response parsing rejects `cast_to` values that are subclasses of httpx response classes (e.g. a custom subclass of httpx.Response). Because the internal ResponseT TypeVar is invariant, the SDK cannot safely return a user-constructed response subclass, so it raises this ValueError to fail fast instead of returning a mistyped object.

Source

Thrown at src/openai/_response.py:219

        if cast_to == bool:
            return cast(R, response.text.lower() == "true")

        # handle the legacy binary response case
        if inspect.isclass(cast_to) and cast_to.__name__ == "HttpxBinaryResponseContent":
            return cast(R, cast_to(response))  # type: ignore

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

        response_types = http_response_types()
        if inspect.isclass(origin) 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. Pass cast_to=httpx.Response exactly if you want the raw response object, or omit cast_to to use the SDK default
2. Use the SDK's built-in `with_raw_response` API wrapper instead of subclassing httpx.Response
3. If you need extra fields, deserialize into a Pydantic model subclassing openai.BaseModel

Example fix

// before
resp = client.get('/v1/models', cast_to=MyHttpResponse)  # subclass of httpx.Response

// after
resp = client.get('/v1/models', cast_to=httpx.Response)

def is_valid_cast_to(cast_to: type) -> bool:
    import httpx
    if isinstance(cast_to, type) and issubclass(cast_to, httpx.Response):
        return cast_to is httpx.Response
    return True

try:
    resp = client.get('/foo', cast_to=MyResponse)
except ValueError as e:
    if 'cast_to' in str(e):
        resp = client.get('/foo', cast_to=httpx.Response)

When it happens

Trigger: Calling any API method with `cast_to=MyResponse` where MyResponse subclasses httpx.Response (or another HTTP response class) but is not exactly the httpx.Response class itself, e.g. client.get('/foo', cast_to=CustomResponse).

Common situations: Developers migrating from raw httpx usage who wrap responses in custom classes, or who try to use `with_raw_response`-style patterns by passing a response subclass to cast_to.

Related errors

• Subclasses of HTTP response classes cannot be passed to `cas
• 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
• Pydantic models must subclass our base model type, e.g. `fro

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