What causes "Failed to parse Azure DI operation response: {e}" in BerriAI/litellm?

Check the embedded exception text — it usually reveals a JSONDecodeError on an HTML/plain-text body, pointing at auth or URL problems.

BerriAI/litellm · error · ValueError

Failed to parse Azure DI operation response: {e}

Error message

Failed to parse Azure DI operation response: {e}

What it means

Catch-all parse failure while checking an Azure DI operation-status response: response.json() threw, or evaluating the body raised, and the exception text did not contain 'succeeded'/'failed' (those are re-raised as-is). It means the polled URL did not return the expected JSON operation document — most often an auth error page, an HTML 404/401 from an expired operation URL, or a proxy interception.

Source

Thrown at litellm/llms/azure_ai/ocr/document_intelligence/transformation.py:495

            status: Final = result.get("status")

            verbose_logger.debug("Azure DI operation status: %s", status)

            if status == "succeeded":
                return "succeeded"
            elif status == "failed":
                error_msg: Final = result.get("error", {}).get("message", "Unknown error")
                raise ValueError(f"Azure Document Intelligence analysis failed: {error_msg}")
            elif status in ["running", "notStarted"]:
                return "running"
            else:
                raise ValueError(f"Unknown operation status: {status}")

        except Exception as e:
            if "succeeded" in str(e) or "failed" in str(e):
                raise
            # If we can't parse JSON, something went wrong
            raise ValueError(f"Failed to parse Azure DI operation response: {e}")

    def _poll_operation_sync(
        self,
        operation_url: str,
        headers: dict[str, str],
        timeout_secs: int,
    ) -> httpx.Response:
        """
        Poll Azure Document Intelligence operation until completion (sync).

        Azure DI POST returns 202 with Operation-Location header.
        We need to poll that URL until status is "succeeded" or "failed".

        Args:
            operation_url: The Operation-Location URL to poll
            headers: Request headers (including auth)
            timeout_secs: Total timeout in seconds

View on GitHub (pinned to 6c2dcb801b)

Solutions

Check the embedded exception text — it usually reveals a JSONDecodeError on an HTML/plain-text body, pointing at auth or URL problems.
Verify AZURE_DOCUMENT_INTELLIGENCE_API_KEY is still valid and matches the resource that issued the operation URL.
Reduce total processing time (smaller docs) or retry the whole analyze operation fresh if the operation URL expired.

Defensive patterns

Strategy: retry

Try / catch

try:
    resp = litellm.aocr_document(model=m, document=doc)
except ValueError as e:
    if "Failed to parse Azure DI operation response" in str(e):
        # likely auth/URL issue mid-poll: verify key, then retry fresh once
        verify_di_credentials()
        resp = litellm.aocr_document(model=m, document=doc)
    else:
        raise

Prevention

Avoid rotating DI credentials while long analyses are in flight.
Keep documents small enough to finish well within operation URL lifetimes.

When it happens

Trigger: Polling an Operation-Location URL that expired or was invalidated (key rotated mid-operation); the subscription key being wrong so the poll returns a non-JSON error; a gateway returning HTML; the operation URL being malformed.

Common situations: Long analyses outliving operation URLs; credential rotation during processing; misconfigured proxies; mocking frameworks returning plain text.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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