BerriAI/litellm · error · BlackForestLabsError

BFL initial request failed: {initial_response.text}

Error message

BFL initial request failed: {initial_response.text}

What it means

After the sync submission POST returns, its status code is checked before anything else. Any response >= 400 (BFL rejecting the create-job request: invalid key 401, quota 429, bad payload 400, server 5xx) is re-raised as BlackForestLabsError preserving the upstream status and body text. The body text carries BFL's own error details.

Source

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

            litellm_params=litellm_params_dict,
            encoding=None,
        )

    def _poll_for_result_sync(
        self,
        initial_response: httpx.Response,
        headers: dict,
        sync_client: HTTPHandler,
        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']}",

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Read initial_response.text in the message — BFL states the exact reason (auth, quota, validation).
2. 401/403: rotate/renew BFL_API_KEY.
3. 429: back off, check your BFL billing/limits, reduce concurrency.
4. 400: fix the flagged request field; 5xx: retry with backoff or wait for BFL status to clear.

null

null

from litellm.exceptions import APIError

try:
    img = litellm.image_generation(model=M, prompt=p)
except APIError as e:
    sc = getattr(e, "status_code", None)
    if sc == 429:
        backoff_and_retry()
    elif sc in (401, 403):
        alert_config("BFL key rejected")
    elif sc and sc >= 500:
        retry_once()
    else:
        raise

When it happens

Trigger: litellm.image_generation on a black_forest_labs model where BFL answers the POST with 4xx/5xx — invalid or revoked API key (401), malformed/missing prompt or params (400), rate limit or exhausted credits (429), BFL internal errors (5xx).

Common situations: Expired BFL keys; hitting the free-tier credit ceiling; prompt validation failures; regional endpoint maintenance; sending parameters the endpoint does not accept.

Related errors

• Polling failed: {response.text}
• {completion_response["error"]}
• err.response.text
• BFL_API_KEY is not set. Please set it via environment variab
• Request failed: {e}

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