DemoAPI 参考文档FAQ

PDF 生成模板编辑器

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

查看 GitHub

模板生成 PDF 错误码 ​

本文说明 POST /api/v1/process/pdf/generation/template-to-pdf 接口的错误码。错误响应中，HTTP 状态码位于 code，ComPDF 服务码位于 bizCode。

错误响应格式 ​

json
{
  "code": "500",
  "msg": "HTML_CONVERTER_ERROR_TEMPLATE_PARSE",
  "data": null,
  "errorCode": "SDK_PROCESS_FAILED",
  "bizCode": 190001,
  "traceId": "d971b49f-4353-494c-963e-1c14918e23be"
}
字段类型说明
codestring代理返回的 HTTP 状态码字符串。
msgstring错误描述。bizCode=190001 时包含 HTML_CONVERTER_* SDK 枚举名称。
datanull错误响应固定为 null。
errorCodestring代理归一化后的语义错误码。
bizCodenumberComPDF 服务码；代理或上游未提供时可能省略。
traceIdstring本次代理请求的追踪 ID，排查问题时请一并提供。
detailsunknown上游提供的可选错误详情。

服务错误码 ​

100xxx - 请求与文件错误 ​

错误码errorCodeHTTP用户提示技术说明
100001INVALID_ARGUMENT400参数无效。请检查输入内容后重试。请求参数缺失、类型不正确，或转换参数无效。
100002INVALID_JSON400JSON 解析失败。请检查 JSON 格式后重试。request JSON 或模板数据 JSON 无法解析。
100102FILE_REQUIRED400缺少模板生成所需的文件或请求部件。提供 templateFile，或提供上游支持的模板内容。
100104FILE_TOO_LARGE413上传内容或 htmlUrl 返回内容超过服务限制。缩小输入文件后重新提交。
100106INVALID_OUTPUT_FILE_NAME400outputFileName 包含非法路径片段。使用不含目录或路径遍历字符的文件名。

190xxx - 处理与系统错误 ​

错误码errorCodeHTTP用户提示技术说明
190001SDK_PROCESS_FAILED500由 msg 中的 SDK 枚举决定。ComPDF SDK 返回了非成功的 HTML 转换结果。
190002TEMP_FILE_WRITE_FAILED500PDF 保存失败。请确认存储位置可用后重试。服务端临时目录、上传保存位置或 PDF 输出写入失败。
190003TEMP_FILE_READ_FAILED500文件读取失败。请确认文件存在且可访问，然后重试。服务端读取上传的 HTML、模板或数据文件失败。
190999INTERNAL_ERROR500发生未知错误。请稍后重试；如问题持续，请联系支持团队。未被专门处理的服务内部异常。

SDK 转换错误 ​

下表仅适用于 bizCode=190001。SDK 的原始 ID 不会直接作为 HTTP 响应中的错误码返回，必须结合 msg 的枚举名称判断失败阶段。

SDK IDmsg 枚举用户提示技术说明
-1HTML_CONVERTER_ERROR_FILE_READ文件读取失败。请确认文件存在且可访问，然后重试。输入 HTML 或相关资源读取失败。
-2HTML_CONVERTER_ERROR_HTML_PARSEHTML 解析失败。请检查 HTML 结构和语法后重试。HTML 解析失败。
-3HTML_CONVERTER_ERROR_RENDERHTML 渲染失败。请检查内容或样式后重试。HTML 渲染失败。
-4HTML_CONVERTER_ERROR_PDF_SAVEPDF 保存失败。请确认存储位置可用后重试。PDF 保存失败。
-5HTML_CONVERTER_ERROR_INVALID_PARAM参数无效。请检查输入内容后重试。SDK 判定转换参数无效。
-6HTML_CONVERTER_ERROR_JSON_PARSEJSON 解析失败。请检查 JSON 格式后重试。模板数据 JSON 解析失败。
-7HTML_CONVERTER_ERROR_TEMPLATE_PARSE模板解析失败。请检查标签闭合、嵌套顺序及 ComPDF Generation 语法兼容性；若仍有问题，请联系技术团队。模板语法解析失败。
-8HTML_CONVERTER_ERROR_TEMPLATE_RENDER模板语法正确，但数据代入失败。请检查占位符、数组或对象类型；超过 1000 条或超时时，可尝试分批处理。模板语法正确，但数据代入失败。
-9HTML_CONVERTER_ERROR_LICENSE_NOT_INIT许可证未初始化。请先初始化许可证后重试。Generation 许可证未初始化。
-10HTML_CONVERTER_ERROR_LICENSE_INVALID许可证无效。请检查许可证配置后重试。Generation 许可证无效。
-11HTML_CONVERTER_ERROR_LICENSE_EXPIRED许可证已过期。请更新许可证后重试。Generation 许可证已过期。
-12HTML_CONVERTER_ERROR_LICENSE_NO_PERMISSION许可证没有执行此操作的权限。请检查许可证权限。许可证没有 Generation 操作权限。
-13HTML_CONVERTER_ERROR_UNKNOWN发生未知错误。请稍后重试；如问题持续，请联系支持团队。SDK 无法归类的错误。

重试建议 ​

错误码是否建议直接重试建议
100001、100002、100102、100104、100106否先修正请求、文件或 JSON。
190001视枚举而定参数、模板、数据和许可证问题须先修正；文件读取、渲染和保存问题可在确认环境后重试。
190002、190003是检查存储或输入文件后重试。
190999是采用短暂退避；问题持续时提供 traceId。