What causes "Error parsing OpenRouter response: {e}" in BerriAI/litellm?

Log the exception's status_code and headers, then replay the request with curl to inspect the raw body

BerriAI/litellm · error · OpenRouterException

Error parsing OpenRouter response: {e}

Error message

Error parsing OpenRouter response: {e}

What it means

LiteLLM's OpenRouter image-generation handler calls raw_response.json() before populating the ImageResponse. If the response body is not valid JSON, the parser's exception is wrapped in an OpenRouterException forwarding the real HTTP status code and headers, with the parse error embedded in the message.

Source

Thrown at litellm/llms/openrouter/image_generation/transformation.py:347

        Args:
            model: The model name
            raw_response: Raw HTTP response from OpenRouter
            model_response: ImageResponse object to populate
            logging_obj: Logging object
            request_data: Original request data
            optional_params: Optional parameters
            litellm_params: LiteLLM parameters
            encoding: Encoding
            api_key: API key
            json_mode: JSON mode flag

        Returns:
            ImageResponse: Populated image response
        """
        try:
            response_json: Final = raw_response.json()
        except Exception as e:
            raise OpenRouterException(
                message=f"Error parsing OpenRouter response: {e}",
                status_code=raw_response.status_code,
                headers=raw_response.headers,
            )

        if not model_response.data:
            model_response.data = []

        try:
            choices: Final = response_json.get("choices", [])

            for choice in choices:
                message = choice.get("message", {})
                images = message.get("images", [])

                for image_data in images:
                    image_url_obj = image_data.get("image_url", {})
                    image_url = image_url_obj.get("url")

View on GitHub (pinned to 77b7c6c40c)

Solutions

Log the exception's status_code and headers, then replay the request with curl to inspect the raw body
Confirm OPENROUTER_API_KEY is valid and the model is available for image generation
Remove or fix any custom api_base override
Retry transient 5xx/non-JSON responses with backoff

Defensive patterns

Strategy: try-catch

Try / catch

Catch OpenRouterException around litellm.image_generation(); if the message starts with 'Error parsing', the body was not JSON - log status_code/headers, retry once with backoff for transient gateway errors, and fall back to another image provider if it persists.

Prevention

Validate the API key and model availability before entering image-generation flows
Do not point api_base at proxies that can return HTML error pages
Monitor for bursts of parse failures as an early signal of provider incidents

When it happens

Trigger: Calling litellm.image_generation() with an openrouter/* model when the endpoint returns a non-JSON body: gateway HTML pages, empty bodies from timed-out upstreams, plain-text rate-limit or auth errors, or a custom api_base that returns non-JSON.

Common situations: OpenRouter maintenance windows returning HTML; invalid API key producing a non-JSON auth error; routing through a corporate proxy that injects HTML block pages.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/ef9f11d46da4f397. Report an issue: GitHub.