BerriAI/litellm · error · BlackForestLabsError

BFL error

Error message

BFL error: {response_data['errors']}

What it means

Sync BFL flow: the initial response parsed as JSON and contains an `errors` key, which the BFL API uses to report request-level problems (validation, auth, credits) even alongside a 2xx-ish status. LiteLLM surfaces it as BlackForestLabsError with the initial status code and the raw `errors` value in the message, so the actionable detail is inside the message text.

Solutions

1. Read the `errors` payload embedded in the exception message - it names the offending field or reason.
2. Correct the named request parameter (type/range) per BFL's API docs for the exact model.
3. Check account credits/permissions in the BFL dashboard if the error mentions quota or access.
4. Upgrade LiteLLM so any request-shape fixes for newer BFL validations are applied.

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 str(e).startswith("BFL error:"):
        errors = json.loads(str(e)[len("BFL error:"):].strip())
        surface_field_errors(errors)   # show user which param was wrong
    else:
        raise

When it happens

Trigger: BFL accepting the HTTP request but rejecting it semantically: invalid parameter values (e.g. unsupported aspect_ratio or seed type), prompt failing server-side validation, insufficient credits flagged at submission, or key lacking permission for the requested model.

Common situations: First runs against a new BFL model before reading its parameter schema; draining a prepaid credit balance mid-batch; account-level restrictions on certain FLUX models; API version drift where a formerly-valid field value is now rejected.

Related errors

• BFL initial request failed
• Error parsing BFL response
• Error parsing initial response
• Image generation failed
• Max recursion depth reached while reading image bytes for…

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

Appendix: source

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

        # 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",
            )

        # Reject polling URLs that don't belong to BFL-controlled infrastructure.
        # BFL uses regional subdomains (e.g. gateway.bfl.ai) that differ from the
        # submission host (api.bfl.ai), so we validate against the registered
        # domain rather than doing a strict same-origin check. VERIA-51.
        assert_bfl_polling_url(polling_url)

        # Get just the auth header for polling

View on GitHub (pinned to 77b7c6c40c)