What causes "BFL error: {response_data['errors']}" in BerriAI/litellm?

Read the forwarded errors array — it contains BFL's specific per-issue messages.

BerriAI/litellm · error · BlackForestLabsError

BFL error: {response_data['errors']}

Error message

BFL error: {response_data['errors']}

What it means

If the parsed submission JSON contains an 'errors' key, BFL reported a problem at job creation and the handler raises immediately, forwarding the errors array verbatim. This is BFL's structured rejection channel — the payload arrived and parsed, but BFL refused to create the job.

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 6c2dcb801b)

Solutions

Read the forwarded errors array — it contains BFL's specific per-issue messages.
Adjust the prompt/params exactly as the message indicates (rephrase moderated content, fix invalid values).
If the error is quota/billing-related in the details, settle the BFL account limits before retrying.
Reproduce with a minimal prompt to isolate which input element triggered it.

Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

try:
    img = litellm.image_generation(model=M, prompt=p)
except Exception as e:
    if "BFL error:" in str(e):
        detail = str(e)
        if "moderat" in detail.lower():
            return safer_prompt_fallback(p)
        raise

Prevention

Pre-screen prompts with your own moderation filter to avoid wasted submissions.
Treat 'BFL error:' payloads as authoritative — fix the named field, don't retry blindly.
Wrap batch jobs so one rejected prompt doesn't kill the batch.

When it happens

Trigger: Submission responses like {"errors":[{"message":"Invalid prompt",...}]} — prompt moderation refusals, invalid parameter values, or API misuse recognized synchronously by BFL.

Common situations: Prompts tripping BFL content moderation; unsupported parameter combinations; model/endpoint misuse; policy-restricted content in prompt or referenced images.

Related errors

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