openai/openai-python · error · APIResponseValidationError

Expected Content-Type response header to be `application/jso

Error message

Expected Content-Type response header to be `application/json` but received `{content_type}` instead.

What it means

When the client is configured with strict_response_validation=True, any response whose Content-Type header is not exactly application/json triggers APIResponseValidationError. Normally non-JSON content types fall back to returning the raw text, but strict mode turns this into an error.

Source

Thrown at src/openai/_response.py:259

        # split is required to handle cases where additional information is included
        # in the response, e.g. application/json; charset=utf-8
        content_type, *_ = response.headers.get("content-type", "*").split(";")
        if not content_type.endswith("json"):
            if is_basemodel(cast(type, cast_to)):
                try:
                    data = response.json()
                except Exception as exc:
                    log.debug("Could not read JSON from response data due to %s", type(exc).__name__)
                else:
                    return self._client._process_response_data(
                        data=data,
                        cast_to=cast_to,  # type: ignore
                        response=response,
                    )

            if self._client._strict_response_validation:
                raise APIResponseValidationError(
                    response=response,
                    message=f"Expected Content-Type response header to be `application/json` but received `{content_type}` instead.",
                    body=response.text,
                )

            # If the API responds with content that isn't JSON then we just return
            # the (decoded) text without performing any parsing so that you can still
            # handle the response however you need to.
            return response.text  # type: ignore

        data = response.json()

        return self._client._process_response_data(
            data=data,
            cast_to=cast_to,  # type: ignore
            response=response,
        )

View on GitHub (pinned to 9917c6e28e)

Solutions

Inspect the response body (included in the exception) to see what the server actually returned and fix the endpoint/proxy returning HTML
Verify base_url points to the real OpenAI API or a compatible JSON API
Disable strict_response_validation if you want lenient text fallback for non-JSON content

Example fix

// before
client = openai.OpenAI(strict_response_validation=True)

// after
client = openai.OpenAI()  # non-JSON falls back to raw text

Defensive patterns

Strategy: try-catch

Try / catch

from openai import APIResponseValidationError
try:
    result = client.chat.completions.create(...)
except APIResponseValidationError as e:
    body = e.body  # inspect what the server actually returned (often HTML)
    raise

Prevention

Only enable strict_response_validation when you control the endpoint
Verify base_url and proxy configuration return application/json responses
Log response bodies on unexpected content types before enabling strict mode

When it happens

Trigger: Setting `openai.OpenAI(strict_response_validation=True)` and receiving a response with a Content-Type such as text/plain, text/html, or application/octet-stream from the API endpoint (often an HTML error page from a proxy or gateway).

Common situations: A corporate proxy, gateway, or captcha page returning HTML instead of JSON; pointing base_url at a wrong/self-hosted endpoint that returns non-JSON 200 responses; enabling strict validation in CI to catch contract drift.

Related errors

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