HKUDS/DeepTutor · error · MinerUError

_http_error_message(exc)

Error message

_http_error_message(exc)

What it means

An HTTP status error (non-429, or 429 with rotation already used) from a MinerU API call is converted into a friendly message via _http_error_message — e.g. 401/403 token rejection guidance.

Source

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

    **kwargs,
) -> dict:
    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."""

View on GitHub (pinned to 3e82f13042)

Solutions

1. Follow the message: for 401/403 re-enter the token in Settings → MinerU.
2. Verify api_base_url and endpoint version.
3. Wait and retry for 5xx/429; rotate additional keys if rate-limited often.
4. Check MinerU status page for outages.

def token_plausible(k: str) -> bool:
    return bool(k) and len(k) >= 16

try:
    verify_credentials(cfg)
except MinerUError as e:
    if "401/403" in str(e):
        prompt_reenter_token()
    else:
        schedule_retry()

When it happens

Trigger: API returns 401/403 (bad token), 404 (wrong api_base_url), 5xx, or a second 429 after the key was already rotated once.

Common situations: Expired/typo'd API token, wrong base URL, quota exceeded, MinerU outage.

Related errors

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

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