{"record":{"id":"2ba553215165a6d5","repo":"BerriAI/litellm","slug":"azure-document-intelligence-operation-polling-time","errorCode":null,"errorMessage":"Azure Document Intelligence operation polling timed out after {timeout_secs} seconds","messagePattern":"Azure Document Intelligence operation polling timed out after (.+?) seconds","errorType":"exception","errorClass":"TimeoutError","httpStatus":null,"severity":"error","filePath":"litellm/llms/azure_ai/ocr/document_intelligence/transformation.py","lineNumber":444,"sourceCode":"            width_px = int(width)\n            height_px = int(height)\n\n        return OCRPageDimensions(width=width_px, height=height_px, dpi=dpi)\n\n    @staticmethod\n    def _check_timeout(start_time: float, timeout_secs: int) -> None:\n        \"\"\"\n        Check if operation has timed out.\n\n        Args:\n            start_time: Start time of the operation\n            timeout_secs: Timeout duration in seconds\n\n        Raises:\n            TimeoutError: If operation has exceeded timeout\n        \"\"\"\n        if time.time() - start_time > timeout_secs:\n            raise TimeoutError(f\"Azure Document Intelligence operation polling timed out after {timeout_secs} seconds\")\n\n    @staticmethod\n    def _get_retry_after(response: httpx.Response) -> int:\n        \"\"\"\n        Get retry-after duration from response headers.\n\n        Args:\n            response: HTTP response\n\n        Returns:\n            Retry-after duration in seconds (default: 2)\n        \"\"\"\n        retry_after: Final = int(response.headers.get(\"retry-after\", \"2\"))\n        verbose_logger.debug(\"Retry polling after: %s seconds\", retry_after)\n        return retry_after\n\n    @staticmethod\n    def _check_operation_status(response: httpx.Response) -> str:","sourceCodeStart":426,"sourceCodeEnd":462,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/azure_ai/ocr/document_intelligence/transformation.py#L426-L462","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nresp = litellm.aocr_document(model=\"azure_ai/doc-intelligence/prebuilt-layout\", document=doc, timeout=60)\n\n# after\nresp = litellm.aocr_document(model=\"azure_ai/doc-intelligence/prebuilt-layout\", document=doc, timeout=600)","handlingStrategy":"retry","validationCode":"def estimate_timeout(num_pages: int) -> int:\n    # rough heuristic: DI analysis takes seconds per page; budget generously\n    return max(120, 5 * num_pages + 60)","typeGuard":null,"tryCatchPattern":"try:\n    resp = litellm.aocr_document(model=m, document=doc, timeout=600)\nexcept TimeoutError as e:\n    # operation may still complete server-side; retry or raise to scheduler\n    log.warning(\"DI analysis timed out: %s\", e)\n    raise","preventionTips":["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."],"tags":["azure","document-intelligence","ocr","timeout","polling"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}