{"record":{"id":"f3a4ae1065ffce63","repo":"docling-project/docling","slug":"error-message","errorCode":null,"errorMessage":"{error_message}","messagePattern":"\\{error_message\\}","errorType":"exception","errorClass":"ServiceUnavailableError","httpStatus":null,"severity":"error","filePath":"docling/service_client/client.py","lineNumber":594,"sourceCode":"            )\n        if response.status_code in {429, 503}:\n            return self._retry_with_retry_after_header(\n                response=response,\n                attempt=attempt,\n                max_retries=max_retries,\n            )\n        return response, 0.0\n\n    def _retry_with_exponential_backoff(\n        self,\n        response: httpx.Response,\n        attempt: int,\n        max_retries: int,\n        error_message: str,\n    ) -> tuple[httpx.Response | None, float]:\n        if attempt < max_retries:\n            return None, self._exponential_backoff_delay(attempt)\n        raise ServiceUnavailableError(\n            error_message,\n            status_code=response.status_code,\n            detail=self._http_error_detail(response),\n        )\n\n    def _retry_with_retry_after_header(\n        self,\n        response: httpx.Response,\n        attempt: int,\n        max_retries: int,\n    ) -> tuple[httpx.Response | None, float]:\n        retry_after_delay = self._retry_after_delay_seconds(response)\n        if retry_after_delay is None:\n            return response, 0.0\n        if attempt < max_retries:\n            return None, retry_after_delay\n        raise ServiceUnavailableError(\n            f\"Service returned HTTP {response.status_code} after retries.\",","sourceCodeStart":576,"sourceCodeEnd":612,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/service_client/client.py#L576-L612","documentation":"In the sync client's retry handling, _retry_with_exponential_backoff is called for retryable HTTP statuses without a Retry-After header. When attempt >= max_retries it gives up and raises ServiceUnavailableError with the caller-provided error_message (which names the failing operation) plus status code and response detail. It marks definitive exhaustion of the exponential backoff budget.","triggerScenarios":"Service returning 5xx (e.g. 500/503) on every attempt for operations like file upload or task submission until retries run out; sustained server errors during batch processing; max_retries set low combined with a briefly failing endpoint.","commonSituations":"docling-serve throwing internal errors on a specific corrupt document; service under heavy load returning 503 for all requests; API rate limiting implemented as plain 503 without Retry-After.","solutions":["Check the service logs for the underlying 5xx cause (often one problematic document).","Increase http_retries so transient 5xx bursts are absorbed.","Isolate and retry the failing request separately; skip the poison document in batch runs.","If errors are deterministic, the document or options may trigger a server bug — report upstream with the detail payload."],"exampleFix":"# before\nclient = DocumentConverterClient(url)  # default retries\nfor f in files:\n    client.convert_file(f)  # ServiceUnavailableError on server 500s\n\n# after\nclient = DocumentConverterClient(url, http_retries=5)\nfor f in files:\n    try:\n        client.convert_file(f)\n    except ServiceUnavailableError as e:\n        log.error('skipping %s: %s', f, e)","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"from docling.service_client.exceptions import ServiceUnavailableError\n\nfor f in files:\n    try:\n        results.append(client.convert_file(f))\n    except ServiceUnavailableError as e:\n        log.error('failed %s status=%s detail=%s', f, e.status_code, e.detail)\n        failed.append(f)  # retry later, don't abort the batch","preventionTips":["Raise http_retries to absorb transient 5xx bursts.","Log and quarantine poison documents instead of failing the whole batch.","Check server logs for deterministic 5xx causes."],"tags":["service-client","retry","http-5xx","unavailable"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}