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 strict_response_validation is enabled on the client, the SDK asserts that JSON-expecting responses carry an application/json Content-Type header. Any other content type (e.g. text/plain, text/html from a proxy or error page) raises APIResponseValidationError instead of leniently attempting to parse the body.

Source

Thrown at src/openai/_legacy_response.py:326

        # 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_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

1. Inspect response headers from the failing endpoint and fix the server/proxy to return application/json for JSON bodies
2. If the endpoint is legitimately non-JSON, cast to str or httpx.Response instead of a model/dict
3. As a last resort, construct the client with strict_response_validation=False to restore lenient parsing

Example fix

# before
client = OpenAI(strict_response_validation=True)
# after
client = OpenAI()  # lenient content-type handling

ct = response.headers.get('content-type', '').split(';')[0]
if ct != 'application/json':
    # handle non-JSON response explicitly (log, alert, or parse as text)
    body = response.text

from openai import APIResponseValidationError
try:
    parsed = response.parse()
except APIResponseValidationError as e:
    if 'Content-Type' in str(e):
        body = e.body  # inspect raw text; likely a proxy/HTML error page
        raise

When it happens

Trigger: Setting client = OpenAI(strict_response_validation=True) and hitting a server/proxy that returns text/html, text/plain, or an unexpected MIME type for a JSON endpoint; API gateways returning HTML error pages or cloud-provider endpoints (Bedrock/Azure front-ends) that alter headers.

Common situations: Enabling strict validation in production behind a corporate proxy or WAF that rewrites responses; pointing the base_url at a gateway whose error responses are HTML; version changes in a provider's header behavior.

Related errors

• Expected Content-Type response header to be `application/jso
• Subclasses of HTTP response classes cannot be passed to `cas
• StreamAlreadyConsumed
• Passing raw bytes as `body` is deprecated and will be remove

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