What causes "Doc2x return an error: Trace ID: {trace_id} {uid} {code} - {meg}" in binary-husky/gpt_academic?

Read the code and message fields in the error — they name the application-level reason

binary-husky/gpt_academic · error · RuntimeError

Doc2x return an error: Trace ID: {trace_id} {uid} {code} - {

Error message

Doc2x return an error:
Trace ID: {trace_id} {uid}
{code} - {meg}

What it means

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.

Source

Thrown at crazy_functions/pdf_fns/parse_pdf_via_doc2x.py:69

    Check the status of Doc2x API response
    Args:
        response_data: Response object from Doc2x API
    """
    response_json = response.json()
    response_data = response_json.get("data", {})
    code = response_json.get("code", "Unknown")
    meg = response_data.get("message", response_json)
    trace_id = response.headers.get("trace-id", "Failed to get trace-id")
    if response.status_code != 200:
        raise RuntimeError(
            f"Doc2x return an error:\nTrace ID: {trace_id} {uid}\n{response.status_code} - {response_json}"
        )
    if code in ["parse_page_limit_exceeded", "parse_concurrency_limit"]:
        raise RuntimeError(
            f"Reached the limit of Doc2x:\nTrace ID: {trace_id} {uid}\n{code} - {meg}"
        )
    if code not in ["ok", "success"]:
        raise RuntimeError(
            f"Doc2x return an error:\nTrace ID: {trace_id} {uid}\n{code} - {meg}"
        )
    return response_data


def 解析PDF_DOC2X_转Latex(pdf_file_path):
    zip_file_path, unzipped_folder = 解析PDF_DOC2X(pdf_file_path, format="tex")
    return unzipped_folder


def 解析PDF_DOC2X(pdf_file_path, format="tex"):
    """
    format: 'tex', 'md', 'docx'
    """

    DOC2X_API_KEY = get_conf("DOC2X_API_KEY")
    latex_dir = get_log_folder(plugin_name="pdf_ocr_latex")
    markdown_dir = get_log_folder(plugin_name="pdf_ocr")

View on GitHub (pinned to d6bde0fa54)

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

Defensive patterns

Strategy: try-catch

Validate before calling

ALLOWED_CODES = {'ok', 'success', 'parse_page_limit_exceeded', 'parse_concurrency_limit'}
def has_known_code(response_json: dict) -> bool:
    return response_json.get('code') in ALLOWED_CODES

Try / catch

try:
    data = doc2x_api_response_status(res)
except RuntimeError as e:
    code = parse_code_from_error(str(e))
    if code in ('invalid_file_format', 'file_too_large'):
        quarantine(pdf_path); continue  # batch: skip bad file
    raise

Prevention

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

When it happens

Trigger: 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.

Common situations: Passing a .docx or image disguised as .pdf; stale uuid after long waits between upload and convert steps; Doc2x API changes introducing undocumented codes.

Related errors

AI-assisted analysis of binary-husky/gpt_academic@d6bde0fa54 (2026-08-14). Data as JSON: /api/errors/dfd8391f192d887b. Report an issue: GitHub.