{"record":{"id":"ae075ae7c7683226","repo":"HKUDS/DeepTutor","slug":"mineru-api-error-code-code-msg","errorCode":null,"errorMessage":"MinerU API error (code {code}): {msg}","messagePattern":"MinerU API error \\(code (.+?)\\): (.+?)","errorType":"exception","errorClass":"MinerUError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/parsing/engines/mineru/cloud.py","lineNumber":302,"sourceCode":"\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.\")\n    code = payload.get(\"code\")\n    if code not in (0, None):\n        msg = str(payload.get(\"msg\") or \"unknown error\")\n        raise MinerUError(f\"MinerU API error (code {code}): {msg}\")\n\n\ndef _http_error_message(exc: httpx.HTTPStatusError) -> str:\n    status = exc.response.status_code\n    if status in (401, 403):\n        return \"MinerU API rejected the token (401/403). Check the API token in Settings → MinerU.\"\n    if status == 429:\n        return \"MinerU API rate limit hit (429). Try again later or reduce request volume.\"\n    return f\"MinerU API returned HTTP {status}.\"\n\n\ndef _reset_dir(path: Path) -> None:\n    if path.exists():\n        import shutil\n\n        shutil.rmtree(path)\n    path.mkdir(parents=True, exist_ok=True)\n","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/parsing/engines/mineru/cloud.py#L284-L320","documentation":"MinerU returns HTTP 200 but wraps failures in a business code; payload['code'] was non-zero (and not None), with the server's msg attached.","triggerScenarios":"_check_code seeing code like 401 (invalid token), quota errors, invalid parameters, or file-rejected — all with HTTP 200.","commonSituations":"Classic MinerU pattern: quota exceeded, token invalid, or bad request params (model_version, enable_formula) that still return 200.","solutions":["Read (code, msg) — they map to MinerU's documented error codes.","Fix the named cause: token, quota, or parameter values.","Retry after resolving; codes like quota errors clear with time/upgrade."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"# pre-validate the params you control\nassert cfg.model_version in {\"v2\", \"pipeline\"}, cfg.model_version","typeGuard":null,"tryCatchPattern":"except MinerUError as e:\n    m = re.search(r\"code (\\d+)\", str(e))\n    if m and m.group(1) in QUOTA_CODES:\n        notify_quota(); backoff()\n    else:\n        surface_error(str(e))","preventionTips":["Keep a map of MinerU business codes for triage.","Validate model_version/flags against docs before submitting.","Monitor quota usage to pre-empt quota-code errors."],"tags":["mineru","cloud","api-error"],"backgroundTag":"api-business-error-code","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}