{"record":{"id":"0f4cbd8583fa3acb","repo":"HKUDS/DeepTutor","slug":"mineru-api-request-failed-exc","errorCode":null,"errorMessage":"MinerU API request failed: {exc}","messagePattern":"MinerU API request failed: (.+?)","errorType":"exception","errorClass":"MinerUError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/parsing/engines/mineru/cloud.py","lineNumber":280,"sourceCode":"    for attempt in range(2):\n        api_key = key_pool.next()\n        try:\n            response = request(\n                path,\n                timeout=_SUBMIT_TIMEOUT_SECONDS,\n                headers={\"Authorization\": f\"Bearer {api_key}\"},\n                **kwargs,\n            )\n            response.raise_for_status()\n            payload = response.json()\n        except httpx.HTTPStatusError as exc:\n            if exc.response.status_code == 429:\n                key_pool.mark_429(api_key)\n                if attempt == 0:\n                    continue\n            raise MinerUError(_http_error_message(exc)) from exc\n        except httpx.HTTPError as exc:\n            raise MinerUError(f\"MinerU API request failed: {exc}\") from exc\n        _check_code(payload)\n        return payload\n    raise MinerUError(\"MinerU API key rotation exhausted.\")\n\n\ndef _post_json(client: httpx.Client, path: str, body: dict, key_pool: KeyPool) -> dict:\n    return _request_json(client.post, path, key_pool, json=body)\n\n\ndef _get_json(client: httpx.Client, path: str, key_pool: KeyPool) -> dict:\n    return _request_json(client.get, path, key_pool)\n\n\ndef _check_code(payload: dict) -> None:\n    \"\"\"MinerU wraps errors in ``{\"code\": <non-zero>, \"msg\": ...}`` even on\n    HTTP 200, so the business code must be inspected explicitly.\"\"\"\n    if not isinstance(payload, dict):\n        raise MinerUError(\"MinerU API returned an unexpected (non-JSON) response.\")","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/parsing/engines/mineru/cloud.py#L262-L298","documentation":"A non-status httpx.HTTPError (connect error, read timeout, TLS failure) occurred while calling a MinerU API endpoint.","triggerScenarios":"Connection refused/DNS failure to the MinerU host, TLS handshake issues, or request timeout before any HTTP status is received.","commonSituations":"No internet, firewall blocking the API host, self-signed proxy MITM, transient network blips.","solutions":["Check connectivity: curl the api_base_url from the same host.","Fix proxy/TLS config (trust store, HTTP_PROXY env).","Retry — transient network errors are common.","Confirm api_base_url is correct and reachable."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import socket, httpx\ndef api_reachable(base_url: str) -> bool:\n    try:\n        httpx.get(base_url, timeout=5); return True\n    except httpx.HTTPError:\n        return False","typeGuard":null,"tryCatchPattern":"except MinerUError as e:\n    if \"API request failed\" in str(e):\n        backoff_and_retry(max_attempts=3)","preventionTips":["Health-check the API base URL before batch jobs.","Configure proxies/trust stores correctly.","Retry transient connect/read errors with backoff."],"tags":["mineru","cloud","network","connection"],"backgroundTag":"network-request-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}