DemoAPI 参考文档FAQ

PDF 生成模板编辑器

开源可视化 PDF 生成引擎，支持自定义模板，并提供面向开发者的 API，灵活构建文档生成流程。

查看 GitHub

错误码 ​

本页面用于查看 Self-hosted PDF 的统一错误码、错误名称、所属模块和处理建议。

错误码范围 ​

提示

本页面适用于 Self-hosted PDF 的 PDF 处理与转档接口。一个统一错误码可能对应不同模块的错误名称，需要结合模块标签和容器日志进行定位。

错误响应 ​

  • HTTP 状态码用于判断请求是否成功。
  • 统一错误码用于定位具体的服务、模块或处理引擎问题。
json
{
  "type": "conversion",
  "code": 4,
  "errorCode": "PDF_PAGE_ERROR",
  "message": "PDF page failed to load.",
  "traceId": "82f733c63cc74946a7c5671430e3c6a4"
}

字段说明 ​

字段类型说明
typeString错误来源：conversion、pdf 或 server。
codeNumber来源返回的数字错误码。转档 SDK 错误可以使用原始 SDK 错误码，API 与服务器端错误通常使用六位数字业务码。
errorCodeString与 code 对应的稳定语义错误标识。
messageString英文可读错误信息。已文档化的处理错误使用对应 SDK 错误定义中的英文说明。
traceIdString用于关联请求和服务日志的追踪 ID。

HTTP错误码 ​

HTTP状态codeerrorCode message
200处理错误码 (处理 errorCode)errorCode转档或 PDF 处理发生业务错误。通过 type 区分 conversion 与 pdf。
400100001BAD_REQUEST / VALIDATION_ERROR服务器端请求参数缺失或无效。
401140001UNAUTHORIZED缺少或传入了无效的 x-api-key / 管理端会话。
403140002FORBIDDEN / INVALID_TOKEN当前请求无权执行。
404150001NOT_FOUND资源或任务不存在。
409150002 / 150003TASK_NOT_READY / CONFLICT / INVALID_STATE任务或资源状态不允许当前请求。
413100104FILE_TOO_LARGE文件在进入底层处理前超过 ComPDF Self-hosted 请求限制。
429130012CONCURRENCY_LIMIT同时到达 ComPDF Self-hosted 的请求过多。
500190999INTERNAL_ERROR未预期的服务器端错误。

业务错误码 ​

本表中的所有处理错误均使用 HTTP 200 返回。转档错误目录包含 4（PDF_PAGE_ERROR）等原始数字错误码及六位转档 API 错误码。解释重复数值前请先确认对应的 type。

codeerrorCode类别错误说明
100001INVALID_REQUESTconversion请求或参数无效。
100001INVALID_ARGUMENTpdf请求或参数无效。
100002INVALID_JSONpdfrequest 或 options 不是合法 JSON。
100002INVALID_JSONconversionrequest 或 options 不是合法 JSON。
100101INVALID_FILE_TYPEpdf上传文件类型不支持。
100101INVALID_FILE_TYPEconversion上传文件类型不支持。
100102FILE_REQUIREDpdf缺少必须的文件字段。
100102FILE_REQUIREDconversion缺少必须的文件字段。
100103FILE_COUNT_MISMATCHpdf文件数量和参数不匹配。
100104FILE_TOO_LARGEpdf上传文件超过大小限制。
100105PAGE_LIMIT_EXCEEDEDpdf超过页面数量限制。
100106INVALID_OUTPUT_FILE_NAMEpdf输出文件名非法。
110001INVALID_PAGE_RANGEpdf页码范围非法。
110001INVALID_PAGE_RANGEpdf页码范围非法。
110002INVALID_PAGE_INDEXpdf页面索引非法。
110003INVALID_RECTpdf矩形参数非法。
110004INVALID_QUAD_RECTSpdf多区域坐标参数非法。
110005PAGE_RANGE_EMPTYpdf页码范围未命中页面。
120001AUTH_REQUIREDconversion转档需要认证。
120001PASSWORD_REQUIREDpdfPDF 处理需要密码。
120002INVALID_TOKENconversion转档 Token 无效。
120002INVALID_PASSWORDpdfPDF 处理密码错误。
120201ICC_PROFILE_REQUIREDpdf缺少 ICC profile 文件。
120202ICC_PROFILE_INVALIDpdfICC profile 文件无效。
130003INVALID_STATEpdf当前任务状态不允许操作。
190001CONVERT_FAILEDconversion转档失败。
190001SDK_PROCESS_FAILEDpdfSDK 处理失败。
190002PDF_PASSWORD_ERRORconversion转档密码错误。
190002TEMP_FILE_WRITE_FAILEDpdfPDF 处理临时文件写入失败。
190003PDF_FORMAT_ERRORconversion转档 PDF 格式错误。
190003TEMP_FILE_READ_FAILEDpdfPDF 处理临时文件读取失败。
190004PDF_SECURITY_ERRORconversion转档 PDF 安全错误。
190004RESULT_PACKAGE_FAILEDpdfPDF 处理结果打包失败。
190005OCR_FAILUREconversion转档 OCR 失败。
190005RESOURCE_EXHAUSTEDpdfPDF 处理资源不足。
190006JOB_TIMEOUTconversion转档任务超时。
190006REQUEST_TIMEOUTpdfPDF 处理请求超时。
190009SDK_FILE_ERRORpdf文件无法打开或不存在。
190009SDK_FILE_ERRORconversion文件无法打开或不存在。
190999UPSTREAM_ERRORconversion & PDF未知处理引擎错误。

排查规则 ​

  1. 先确认产品包、API 路径和请求模块。
  2. 再根据统一错误码和错误名称检查输入、权限、资源和处理引擎日志。
  3. 提交问题时提供错误码、错误名称、traceId、请求时间和相关容器日志。