PDF Generation Template Editor
Open-source visual PDF generation engine with customizable templates and developer-friendly APIs.
Error Codes
This page is used to view the unified error codes, error names, modules, and troubleshooting suggestions of Self-hosted PDF.
Error Code Scope
Info
This page applies to the PDF processing and conversion interfaces of Self-hosted PDF. A unified error code may correspond to different error names across modules; use the module tag and container logs for troubleshooting.
Error Response
- HTTP Status Code: Used to determine if a request was successful.
- Unified Error Code: Used to locate specific service, module, or processing engine issues.
json
{
"type": "conversion",
"code": 4,
"errorCode": "PDF_PAGE_ERROR",
"message": "PDF page failed to load.",
"traceId": "82f733c63cc74946a7c5671430e3c6a4"
}Field Description
| Field | Type | Description |
|---|---|---|
type | String | Error source: conversion, pdf, or server. |
code | Number | Numeric error code returned by the source. Conversion SDK errors use original SDK error codes, while API and server errors generally use 6-digit business codes. |
errorCode | String | A stable semantic error identifier corresponding to code. |
message | String | Human-readable error message in English. Documented processing errors use the English description from the corresponding SDK error definitions. |
traceId | String | A trace ID used to correlate requests and service logs. |
HTTP Error Codes
| HTTP Status | code | errorCode | message |
|---|---|---|---|
200 | Processing error codes (handles errorCode) | errorCode | A business error occurred in conversion or PDF processing. Distinguish conversion and pdf by type. |
400 | 100001 | BAD_REQUEST / VALIDATION_ERROR | Server request parameters are missing or invalid. |
401 | 140001 | UNAUTHORIZED | Missing or invalid x-api-key / management session. |
403 | 140002 | FORBIDDEN / INVALID_TOKEN | The current request is not authorized to execute. |
404 | 150001 | NOT_FOUND | The resource or task does not exist. |
409 | 150002 / 150003 | TASK_NOT_READY / CONFLICT / INVALID_STATE | The task or resource state does not allow the current request. |
413 | 100104 | FILE_TOO_LARGE | The file exceeded the ComPDF Self-hosted request limit before entering underlying processing. |
429 | 130012 | CONCURRENCY_LIMIT | Too many requests reached ComPDF Self-hosted simultaneously. |
500 | 190999 | INTERNAL_ERROR | Unexpected server error. |
Business Error Codes
All processing errors in this table are returned with HTTP 200. The conversion error directory includes original numeric error codes such as 4 (PDF_PAGE_ERROR) and six-digit conversion API error codes. Please confirm the corresponding type before interpreting duplicate values.
code | errorCode | Category | Description |
|---|---|---|---|
100001 | INVALID_REQUEST | conversion | Invalid request or parameters. |
100001 | INVALID_ARGUMENT | Invalid request or parameters. | |
100002 | INVALID_JSON | request or options is not valid JSON. | |
100002 | INVALID_JSON | conversion | request or options is not valid JSON. |
100101 | INVALID_FILE_TYPE | Uploaded file type is not supported. | |
100101 | INVALID_FILE_TYPE | conversion | Uploaded file type is not supported. |
100102 | FILE_REQUIRED | Missing required file field. | |
100102 | FILE_REQUIRED | conversion | Missing required file field. |
100103 | FILE_COUNT_MISMATCH | File count and parameters mismatch. | |
100104 | FILE_TOO_LARGE | Uploaded file exceeds size limit. | |
100105 | PAGE_LIMIT_EXCEEDED | Exceeded page count limit. | |
100106 | INVALID_OUTPUT_FILE_NAME | Output file name is invalid. | |
110001 | INVALID_PAGE_RANGE | Page range is invalid. | |
110002 | INVALID_PAGE_INDEX | Page index is invalid. | |
110003 | INVALID_RECT | Rectangle parameter is invalid. | |
110004 | INVALID_QUAD_RECTS | Multiple quad rects parameter is invalid. | |
110005 | PAGE_RANGE_EMPTY | Page range did not hit any pages. | |
120001 | AUTH_REQUIRED | conversion | Conversion requires authentication. |
120001 | PASSWORD_REQUIRED | PDF processing requires password. | |
120002 | INVALID_TOKEN | conversion | Conversion Token is invalid. |
120002 | INVALID_PASSWORD | PDF processing password error. | |
120201 | ICC_PROFILE_REQUIRED | Missing ICC profile file. | |
120202 | ICC_PROFILE_INVALID | Invalid ICC profile file. | |
130003 | INVALID_STATE | Operation not allowed in current task state. | |
190001 | CONVERT_FAILED | conversion | Conversion failed. |
190001 | SDK_PROCESS_FAILED | SDK processing failed. | |
190002 | PDF_PASSWORD_ERROR | conversion | Conversion password error. |
190002 | TEMP_FILE_WRITE_FAILED | PDF temporary file write failed. | |
190003 | PDF_FORMAT_ERROR | conversion | Conversion PDF format error. |
190003 | TEMP_FILE_READ_FAILED | PDF temporary file read failed. | |
190004 | PDF_SECURITY_ERROR | conversion | Conversion PDF security error. |
190004 | RESULT_PACKAGE_FAILED | PDF result package failed. | |
190005 | OCR_FAILURE | conversion | Conversion OCR failed. |
190005 | RESOURCE_EXHAUSTED | PDF processing resources exhausted. | |
190006 | JOB_TIMEOUT | conversion | Conversion job timeout. |
190006 | REQUEST_TIMEOUT | PDF processing request timeout. | |
190009 | SDK_FILE_ERROR | File cannot be opened or does not exist. | |
190009 | SDK_FILE_ERROR | conversion | File cannot be opened or does not exist. |
190999 | UPSTREAM_ERROR | processing engine | Unknown processing engine error. |
Troubleshooting Rules
- First confirm the product package, API path, and request module.
- Then check input, permissions, resources, and processing engine logs according to the unified error code and error name.
- When submitting an issue, provide the Error Code, Error Name,
traceId, request time, and related container logs.