{"record":{"id":"5b6f227a6c9fdb6a","repo":"docling-project/docling","slug":"service-transport-request-failed-5b6f22","errorCode":null,"errorMessage":"Service transport request failed.","messagePattern":"Service transport request failed\\.","errorType":"exception","errorClass":"ServiceUnavailableError","httpStatus":null,"severity":"error","filePath":"docling/service_client/client.py","lineNumber":2277,"sourceCode":"                    method=method_name,\n                    url=url,\n                    json=json,\n                    data=data,\n                    files=files,\n                    params=params,\n                    headers=headers,\n                )\n            except httpx.HTTPError as exc:\n                delay = self._transport_retry_delay(\n                    method=method_name,\n                    exc=exc,\n                    attempt=attempt,\n                    max_retries=max_retries,\n                )\n                if delay is not None:\n                    time.sleep(delay)\n                    continue\n                raise ServiceUnavailableError(\n                    \"Service transport request failed.\",\n                    detail=str(exc),\n                ) from exc\n            result, delay = self._check_retry(response, attempt, max_retries)\n            if result is not None:\n                return result\n            if delay > 0:\n                time.sleep(delay)\n\n        raise ServiceUnavailableError(\"Service request failed after retry loop.\")\n\n    def _failure_message(self, result: ConversionResult) -> str:\n        if result.errors:\n            messages = \"; \".join(item.error_message for item in result.errors)\n            return (\n                f\"Conversion failed for {result.input.file} with status \"\n                f\"{result.status.value}. Errors: {messages}\"\n            )","sourceCodeStart":2259,"sourceCodeEnd":2295,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/service_client/client.py#L2259-L2295","documentation":"ServiceUnavailableError raised when an HTTP request to docling-serve fails at the transport level (httpx.HTTPError) and the retry policy decides not to retry — non-idempotent methods (POST uploads) get no transport retry, or the retry delay budget is exhausted. The original exception is chained and str(exc) is put in detail.","triggerScenarios":"POST-based submit calls (not in TRANSPORT_RETRYABLE_HTTP_METHODS = GET/HEAD/OPTIONS) hitting a connection error, DNS failure, or TLS problem on the first attempt.","commonSituations":"Service pod restarting mid-request; wrong URL scheme/host; TLS cert issues; flaky links combined with non-retryable POST semantics.","solutions":["Check service reachability (curl the /health endpoint) and the URL passed to the client","For transient outages, retry the operation at the application level — POSTs are not auto-retried to avoid duplicate submissions","Fix TLS/proxy configuration if the chained exception indicates certificate or connection failures"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import httpx\nwith httpx.Client(timeout=5) as probe:\n    r = probe.get(f'{service_url}/health')\n    r.raise_for_status()  # fail fast before submitting work","typeGuard":"def is_service_unavailable(exc: BaseException) -> bool:\n    return isinstance(exc, ServiceUnavailableError)","tryCatchPattern":"try:\n    task = client.submit(source)\nexcept ServiceUnavailableError as exc:\n    if exc.detail and 'connect' in exc.detail.lower():\n        backoff_and_resubmit()","preventionTips":["Health-check the service before submitting batches","Wrap submissions in application-level retry — POSTs are not auto-retried"],"tags":["network","service-unavailable","retry","service-client"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}