BerriAI/litellm · error · TimeoutError

Azure Document Intelligence operation polling timed out afte

Error message

Azure Document Intelligence operation polling timed out after {timeout_secs} seconds

What it means

TimeoutError raised by the polling loop for Azure Document Intelligence's asynchronous analyze operation. Azure DI returns 202 with an Operation-Location header; LiteLLM polls that URL and checks elapsed time against the configured timeout (timeout_secs) on each iteration. When time.time() - start_time exceeds the limit, polling stops with this error even though the Azure-side operation may still be running.

Source

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

            width_px = int(width)
            height_px = int(height)

        return OCRPageDimensions(width=width_px, height=height_px, dpi=dpi)

    @staticmethod
    def _check_timeout(start_time: float, timeout_secs: int) -> None:
        """
        Check if operation has timed out.

        Args:
            start_time: Start time of the operation
            timeout_secs: Timeout duration in seconds

        Raises:
            TimeoutError: If operation has exceeded timeout
        """
        if time.time() - start_time > timeout_secs:
            raise TimeoutError(f"Azure Document Intelligence operation polling timed out after {timeout_secs} seconds")

    @staticmethod
    def _get_retry_after(response: httpx.Response) -> int:
        """
        Get retry-after duration from response headers.

        Args:
            response: HTTP response

        Returns:
            Retry-after duration in seconds (default: 2)
        """
        retry_after: Final = int(response.headers.get("retry-after", "2"))
        verbose_logger.debug("Retry polling after: %s seconds", retry_after)
        return retry_after

    @staticmethod
    def _check_operation_status(response: httpx.Response) -> str:

View on GitHub (pinned to 6c2dcb801b)

Solutions

Increase the timeout parameter on the OCR call (e.g. timeout=300) so the poll loop can outlast the analysis.
Reduce document size (fewer pages / smaller scans) or pick a faster model like prebuilt-read for simple text extraction.
Retry the request — Azure may complete faster when load subsides; treat TimeoutError distinctly from ValueErrors so retries are targeted.

Example fix

# before
resp = litellm.aocr_document(model="azure_ai/doc-intelligence/prebuilt-layout", document=doc, timeout=60)

# after
resp = litellm.aocr_document(model="azure_ai/doc-intelligence/prebuilt-layout", document=doc, timeout=600)

Defensive patterns

Strategy: retry

Validate before calling

def estimate_timeout(num_pages: int) -> int:
    # rough heuristic: DI analysis takes seconds per page; budget generously
    return max(120, 5 * num_pages + 60)

Try / catch

try:
    resp = litellm.aocr_document(model=m, document=doc, timeout=600)
except TimeoutError as e:
    # operation may still complete server-side; retry or raise to scheduler
    log.warning("DI analysis timed out: %s", e)
    raise

Prevention

Scale the timeout with document page count.
Use prebuilt-read for speed when layout features aren't needed.
Catch TimeoutError separately from ValueError so only timeouts are retried.

When it happens

Trigger: Analyzing a large/multi-page document where 'running' status persists longer than the passed timeout (sync path: _poll_operation_sync; async path similar); slow Azure regions; tight timeout values like 30s for a 100-page PDF.

Common situations: Default or low timeout for big documents; Azure transient slowness; many concurrent analyses throttling throughput; callers not realizing DI is async and needs a generous budget.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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