BerriAI/litellm · error · BlackForestLabsError

Error parsing initial response

Error message

Error parsing initial response: {e}

What it means

Sync BFL flow: the initial POST returned HTTP < 400, but `initial_response.json()` threw, so the handler wraps the parse exception as BlackForestLabsError with the upstream status code. A success-status response with a non-JSON body is unusual - typically an intermediary (proxy, ingress, captive portal) replaced the body, or the connection truncated mid-body.

Solutions

1. Log the raw body (litellm verbose logging or a custom success handler) to identify who generated the non-JSON response.
2. Bypass or correctly configure the proxy/sidecar for api.bfl.ai.
3. Retry once - truncation cases are transient.
4. Verify the same request with curl from the identical network path; if curl also returns HTML, the problem is outside LiteLLM.

from litellm.llms.black_forest_labs.common_utils import BlackForestLabsError

try:
    resp = litellm.image_generation(model="flux-pro-1.1", prompt=p)
except BlackForestLabsError as e:
    if "Error parsing initial response" in str(e):
        log.error("non-JSON submit response (proxy interference?) status=%s", e.status_code)
        resp = retry_once(lambda: litellm.image_generation(model="flux-pro-1.1", prompt=p))
    else:
        raise

When it happens

Trigger: Corporate proxy or API gateway returning its own 200/3xx HTML page instead of passing BFL's JSON through; captive-portal/WiFi login page intercepting the request; truncated response body from a flaky link causing httpx JSONDecodeError.

Common situations: Enterprise networks with TLS inspection; hotel/airport WiFi before authentication; misconfigured service mesh sidecar responding before upstream; rare truncation on unstable connections. If it reproduces 100% of the time, an interceptor is almost certainly involved.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

Related errors

• Error parsing BFL response
• Cisco AI Defense API returned a non-JSON response
• Image generation failed
• No image URL in BFL result
• No polling_url in BFL response

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

Appendix: source

Thrown at litellm/llms/black_forest_labs/image_generation/handler.py:310

        max_wait: float = DEFAULT_MAX_POLLING_TIME,
        interval: float = DEFAULT_POLLING_INTERVAL,
        timeout: float | httpx.Timeout | None = None,
    ) -> httpx.Response:
        """
        Poll BFL API until result is ready (sync version).
        """
        # Validate initial response status code
        if initial_response.status_code >= 400:
            raise BlackForestLabsError(
                status_code=initial_response.status_code,
                message=f"BFL initial request failed: {initial_response.text}",
            )

        # Parse initial response to get polling URL
        try:
            response_data: Final = initial_response.json()
        except Exception as e:
            raise BlackForestLabsError(
                status_code=initial_response.status_code,
                message=f"Error parsing initial response: {e}",
            )

        # Check for immediate errors
        if "errors" in response_data:
            raise BlackForestLabsError(
                status_code=initial_response.status_code,
                message=f"BFL error: {response_data['errors']}",
            )

        polling_url: Final = response_data.get("polling_url")
        if not polling_url:
            raise BlackForestLabsError(
                status_code=500,
                message="No polling_url in BFL response",
            )

View on GitHub (pinned to 77b7c6c40c)