Template-to-PDF Error Codes

This page describes error codes for POST /api/v1/process/pdf/generation/template-to-pdf. In an error response, the HTTP status is in code, and the ComPDF service code is in bizCode.

Error Response Format

{
  "code": "500",
  "msg": "HTML_CONVERTER_ERROR_TEMPLATE_PARSE",
  "data": null,
  "errorCode": "SDK_PROCESS_FAILED",
  "bizCode": 190001,
  "traceId": "d971b49f-4353-494c-963e-1c14918e23be"
}

Field	Type	Description
code	string	HTTP status code returned by the proxy, as a string.
msg	string	Error description. When bizCode=190001, it contains an HTML_CONVERTER_* SDK enum name.
data	null	Always null in an error response.
errorCode	string	Normalized semantic error code returned by the proxy.
bizCode	number	ComPDF service code. It can be omitted when the proxy or upstream service does not provide it.
traceId	string	Request trace ID. Provide it when troubleshooting.
details	unknown	Optional error details returned by the upstream service.

Service Error Codes

100xxx - Request and File Errors

Code	errorCode	HTTP	User Message	Technical Description
100001	INVALID_ARGUMENT	400	The parameters are invalid. Check the input and try again.	A request parameter is missing, has the wrong type, or is invalid for the conversion.
100002	INVALID_JSON	400	JSON parsing failed. Check the JSON format and try again.	The request JSON or template data JSON cannot be parsed.
100102	FILE_REQUIRED	400	A required file or request part is missing.	Provide templateFile, or template content supported by the upstream service.
100104	FILE_TOO_LARGE	413	The uploaded content or content returned by htmlUrl exceeds the service limit.	Reduce the input size and submit the request again.
100106	INVALID_OUTPUT_FILE_NAME	400	outputFileName contains an invalid path segment.	Use a file name without directory or path-traversal characters.

190xxx - Processing and System Errors

Code	errorCode	HTTP	User Message	Technical Description
190001	SDK_PROCESS_FAILED	500	Determined by the SDK enum in msg.	The ComPDF SDK returned a non-success HTML conversion result.
190002	TEMP_FILE_WRITE_FAILED	500	PDF saving failed. Confirm that the storage location is available and try again.	Writing to the server temporary directory, upload location, or PDF output failed.
190003	TEMP_FILE_READ_FAILED	500	File reading failed. Confirm that the file exists and is accessible, then try again.	Reading the uploaded HTML, template, or data file failed.
190999	INTERNAL_ERROR	500	An unknown error occurred. Try again later; contact support if it persists.	An unhandled internal service exception occurred.

SDK Conversion Errors

The following table applies only when bizCode=190001. The original SDK ID is not returned directly as the HTTP error code; use the enum name in msg to determine the failure stage.

SDK ID	msg Enum	User Message	Technical Description
-1	HTML_CONVERTER_ERROR_FILE_READ	File reading failed. Confirm that the file exists and is accessible, then try again.	The input HTML or related resources could not be read.
-2	HTML_CONVERTER_ERROR_HTML_PARSE	HTML parsing failed. Check the HTML structure and syntax, then try again.	HTML parsing failed.
-3	HTML_CONVERTER_ERROR_RENDER	HTML rendering failed. Check the content or styles, then try again.	HTML rendering failed.
-4	HTML_CONVERTER_ERROR_PDF_SAVE	PDF saving failed. Confirm that the storage location is available and try again.	PDF saving failed.
-5	HTML_CONVERTER_ERROR_INVALID_PARAM	The parameters are invalid. Check the input and try again.	The SDK determined that the conversion parameters are invalid.
-6	HTML_CONVERTER_ERROR_JSON_PARSE	JSON parsing failed. Check the JSON format and try again.	Template data JSON parsing failed.
-7	HTML_CONVERTER_ERROR_TEMPLATE_PARSE	Template parsing failed. Check tag closure, nesting order, and ComPDF Generation syntax compatibility; contact technical support if the issue remains.	Template syntax parsing failed.
-8	HTML_CONVERTER_ERROR_TEMPLATE_RENDER	The template syntax is valid, but data substitution failed. Check placeholders and array or object types; for more than 1,000 items or a timeout, try processing in batches.	The template syntax is valid, but data substitution failed.
-9	HTML_CONVERTER_ERROR_LICENSE_NOT_INIT	The license is not initialized. Initialize the license and try again.	The Generation license is not initialized.
-10	HTML_CONVERTER_ERROR_LICENSE_INVALID	The license is invalid. Check the license configuration and try again.	The Generation license is invalid.
-11	HTML_CONVERTER_ERROR_LICENSE_EXPIRED	The license has expired. Update the license and try again.	The Generation license has expired.
-12	HTML_CONVERTER_ERROR_LICENSE_NO_PERMISSION	The license does not permit this operation. Check its permissions.	The license has no permission for Generation operations.
-13	HTML_CONVERTER_ERROR_UNKNOWN	An unknown error occurred. Try again later; contact support if it persists.	The SDK could not classify the error.

Retry Recommendations

Code	Retry Directly?	Recommendation
100001, 100002, 100102, 100104, 100106	No	Correct the request, file, or JSON first.
190001	Depends on the enum	Correct parameter, template, data, and license issues first. Retry file-reading, rendering, and saving errors after confirming the environment.
190002, 190003	Yes	Check the storage or input file, then retry.
190999	Yes	Use a short backoff. If the problem persists, provide the traceId.