{"record":{"id":"dfd8391f192d887b","repo":"binary-husky/gpt_academic","slug":"doc2x-return-an-error-trace-id-trace-id-uid-dfd839","errorCode":null,"errorMessage":"Doc2x return an error:\nTrace ID: {trace_id} {uid}\n{code} - {meg}","messagePattern":"Doc2x return an error:\nTrace ID: (.+?) (.+?)\n(.+?) - (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"crazy_functions/pdf_fns/parse_pdf_via_doc2x.py","lineNumber":69,"sourceCode":"    Check the status of Doc2x API response\n    Args:\n        response_data: Response object from Doc2x API\n    \"\"\"\n    response_json = response.json()\n    response_data = response_json.get(\"data\", {})\n    code = response_json.get(\"code\", \"Unknown\")\n    meg = response_data.get(\"message\", response_json)\n    trace_id = response.headers.get(\"trace-id\", \"Failed to get trace-id\")\n    if response.status_code != 200:\n        raise RuntimeError(\n            f\"Doc2x return an error:\\nTrace ID: {trace_id} {uid}\\n{response.status_code} - {response_json}\"\n        )\n    if code in [\"parse_page_limit_exceeded\", \"parse_concurrency_limit\"]:\n        raise RuntimeError(\n            f\"Reached the limit of Doc2x:\\nTrace ID: {trace_id} {uid}\\n{code} - {meg}\"\n        )\n    if code not in [\"ok\", \"success\"]:\n        raise RuntimeError(\n            f\"Doc2x return an error:\\nTrace ID: {trace_id} {uid}\\n{code} - {meg}\"\n        )\n    return response_data\n\n\ndef 解析PDF_DOC2X_转Latex(pdf_file_path):\n    zip_file_path, unzipped_folder = 解析PDF_DOC2X(pdf_file_path, format=\"tex\")\n    return unzipped_folder\n\n\ndef 解析PDF_DOC2X(pdf_file_path, format=\"tex\"):\n    \"\"\"\n    format: 'tex', 'md', 'docx'\n    \"\"\"\n\n    DOC2X_API_KEY = get_conf(\"DOC2X_API_KEY\")\n    latex_dir = get_log_folder(plugin_name=\"pdf_ocr_latex\")\n    markdown_dir = get_log_folder(plugin_name=\"pdf_ocr\")","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/binary-husky/gpt_academic/blob/d6bde0fa54373309bd05823a49bda8da019d2c77/crazy_functions/pdf_fns/parse_pdf_via_doc2x.py#L51-L87","documentation":"Doc2x returned HTTP 200 but the body's code field is anything other than 'ok'/'success' (and not one of the known limit codes from error 74). This is the generic application-level failure: the service understood the request but refused or failed it, e.g. invalid file format, unsupported language, malformed uuid, or internal application error. Message includes trace-id, uid, code and server message.","triggerScenarios":"Uploading a non-PDF or corrupt file to the parse endpoint; referencing a uuid that expired or belongs to another account; format parameter not in ('tex','md'); API version drift adding new error codes.","commonSituations":"Passing a .docx or image disguised as .pdf; stale uuid after long waits between upload and convert steps; Doc2x API changes introducing undocumented codes.","solutions":["Read the code and message fields in the error — they name the application-level reason","Verify the input file is a valid PDF (file extension is not enough; check with pdftotext or qpdf --check)","Re-run the full upload→parse→convert flow in one pass so the uuid stays fresh","If the code is unrecognized, check Doc2x changelog/support with the trace-id"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"ALLOWED_CODES = {'ok', 'success', 'parse_page_limit_exceeded', 'parse_concurrency_limit'}\ndef has_known_code(response_json: dict) -> bool:\n    return response_json.get('code') in ALLOWED_CODES","typeGuard":null,"tryCatchPattern":"try:\n    data = doc2x_api_response_status(res)\nexcept RuntimeError as e:\n    code = parse_code_from_error(str(e))\n    if code in ('invalid_file_format', 'file_too_large'):\n        quarantine(pdf_path); continue  # batch: skip bad file\n    raise","preventionTips":["Validate PDF format and size before upload","Parse the code field out of the error to branch on cause instead of string-matching whole messages","Keep the Doc2x SDK/endpoint mapping current when the vendor ships new codes"],"tags":["doc2x","api","application-error","file-validation"],"backgroundTag":null,"analyzedSha":"d6bde0fa54373309bd05823a49bda8da019d2c77","analyzedAt":"2026-08-14T22:48:35.038Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}