HKUDS/DeepTutor · error · MinerUError

MinerU API request failed: {exc}

Error message

MinerU API request failed: {exc}

What it means

A non-status httpx.HTTPError (connect error, read timeout, TLS failure) occurred while calling a MinerU API endpoint.

Source

Thrown at deeptutor/services/parsing/engines/mineru/cloud.py:280

    for attempt in range(2):
        api_key = key_pool.next()
        try:
            response = request(
                path,
                timeout=_SUBMIT_TIMEOUT_SECONDS,
                headers={"Authorization": f"Bearer {api_key}"},
                **kwargs,
            )
            response.raise_for_status()
            payload = response.json()
        except httpx.HTTPStatusError as exc:
            if exc.response.status_code == 429:
                key_pool.mark_429(api_key)
                if attempt == 0:
                    continue
            raise MinerUError(_http_error_message(exc)) from exc
        except httpx.HTTPError as exc:
            raise MinerUError(f"MinerU API request failed: {exc}") from exc
        _check_code(payload)
        return payload
    raise MinerUError("MinerU API key rotation exhausted.")


def _post_json(client: httpx.Client, path: str, body: dict, key_pool: KeyPool) -> dict:
    return _request_json(client.post, path, key_pool, json=body)


def _get_json(client: httpx.Client, path: str, key_pool: KeyPool) -> dict:
    return _request_json(client.get, path, key_pool)


def _check_code(payload: dict) -> None:
    """MinerU wraps errors in ``{"code": <non-zero>, "msg": ...}`` even on
    HTTP 200, so the business code must be inspected explicitly."""
    if not isinstance(payload, dict):
        raise MinerUError("MinerU API returned an unexpected (non-JSON) response.")

View on GitHub (pinned to 3e82f13042)

Solutions

1. Check connectivity: curl the api_base_url from the same host.
2. Fix proxy/TLS config (trust store, HTTP_PROXY env).
3. Retry — transient network errors are common.
4. Confirm api_base_url is correct and reachable.

import socket, httpx
def api_reachable(base_url: str) -> bool:
    try:
        httpx.get(base_url, timeout=5); return True
    except httpx.HTTPError:
        return False

except MinerUError as e:
    if "API request failed" in str(e):
        backoff_and_retry(max_attempts=3)

When it happens

Trigger: Connection refused/DNS failure to the MinerU host, TLS handshake issues, or request timeout before any HTTP status is received.

Common situations: No internet, firewall blocking the API host, self-signed proxy MITM, transient network blips.

Related errors

• Failed to upload PDF to MinerU: {exc}
• Failed to download MinerU result archive: {exc}
• MinerU cloud mode is selected but no API token is configured
• PDF file not found: {pdf_path}
• MinerU API did not return an upload URL (missing batch_id/fi

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/0f4cbd8583fa3acb. Report an issue: GitHub.