Error Codes

Error Response Format

AI service error responses use the following JSON structure:

{
  "success": false,
  "error_code": "DOWNLOAD_TIMEOUT",
  "code": 200002,
  "message": "Human-readable description",
  "detail": {}
}

Field	Type	Description
code	Integer	6-digit numeric error code, programmatic identifier
error_code	String	Semantic error identifier, for readability only
message	String	Error description
detail	Object	Additional context (optional)

Common Service Error Codes

These errors are handled by the service framework and apply to all ComPDF API endpoints.

01xxx — System Errors

Code	HTTP	Description
01001	500	Internal system error
01002	500	Failed to upload processed file to storage
01003	500	File upload error
01004	500	Failed to download your uploaded file
01005	400	File cannot be empty
01006	400	Invalid parameters, please set valid file parameters
01007	400	Task ID cannot be empty

02xxx — File Format Errors

Code	HTTP	Description
02001	400	File format error
02002	400	Unsupported file format for processing
02003	400	Unsupported image format
02201	400	The file is encrypted
02207	400	Failed to open file: unsupported format or encrypted
02209	413	File too large, please upload a smaller file
02210	500	File processing failed
02212	500	File processing failed: abnormal output file size

03000 — Parameter Validation Error

Code	HTTP	Description
03000	400	Parameter validation failed, typically due to missing required fields or incorrect field formats

04xxx — File & Business Errors

Code	HTTP	Description
04001	400	File key does not exist
04002	400	File size is zero
04003	400	File does not exist or cannot be opened
04007	400	Only one file is allowed for this endpoint
04008	400	Merge PDF supports at most 5 files

05xxx — Task Errors

Code	HTTP	Description
05001	404	Task does not exist or is invalid
05002	409	Abnormal task status
05003	400	File count per task has reached the threshold
05004	410	Task expired and was not executed
05005	400	At least one file is required per task

06001 — Insufficient Assets

Code	HTTP	Description
06001	402	You have run out of processing quota, please purchase a plan

Authentication & Authorization

HTTP	Code	Description
401	401	Invalid or missing API Key; authentication service unavailable
403	403	Insufficient permissions

---

AI Functional Error Codes

These errors originate from the AI document parsing and extraction service.

100xxx — Request Parameter Validation

Code	Error Code	HTTP	Description
100001	INVALID_REQUEST	400	Invalid request format
100003	INVALID_JSON	400	JSON parsing failed
100004	INVALID_CONTENT_FILTER	400	Unsupported content_filter value
100005	INVALID_EXTRACT_MODE	400	Unsupported extraction mode
100006	MISSING_FILE	400	Required file is missing
100008	MISSING_EXTRACT_FIELDS	400	Required extract_fields is missing

200xxx — File Download

Code	Error Code	HTTP	Description
200001	DOWNLOAD_FAILED	502	File download failed
200002	DOWNLOAD_TIMEOUT	504	Download request timed out
200003	DOWNLOAD_TOO_LARGE	413	File exceeds configured maximum size
200009	DOWNLOAD_SERVER_DISCONNECTED	502	Remote server disconnected unexpectedly

300xxx — Document Parsing

Code	Error Code	HTTP	Description
300001	PARSE_FAILED	500	Parser execution failed
300002	PARSE_TIMEOUT	504	Parser request timed out
300003	PARSE_PIPELINE_ERROR	502	Parser pipeline service returned an error
300009	PARSE_FILE_TOO_LARGE	413	File exceeds parser size limit

400xxx — Field Extraction

Code	Error Code	HTTP	Description
400001	EXTRACT_FAILED	500	Extraction failed
400002	EXTRACT_TIMEOUT	504	Extraction request timed out
400003	EXTRACT_VLM_ERROR	502	VLM service returned an error
400004	EXTRACT_LLM_ERROR	502	LLM service returned an error
400005	EXTRACT_INVALID_SCHEMA	400	extract_fields schema is invalid
400006	EXTRACT_IMAGE_LOAD_FAILED	500	Failed to load or render image/PDF

500xxx — Object Storage

Code	Error Code	HTTP	Description
500003	STORAGE_UPLOAD_FAILED	500	Upload to storage service failed
500004	STORAGE_DOWNLOAD_FAILED	500	Download from storage service failed
500006	STORAGE_OBJECT_NOT_FOUND	404	Object not found in storage

600xxx — Async Tasks

Code	Error Code	HTTP	Description
600001	TASK_NOT_FOUND	404	Task does not exist
600002	TASK_ALREADY_COMPLETED	400	Task already completed
600003	TASK_ALREADY_CANCELLED	400	Task already cancelled
600005	TASK_RESULT_NOT_FOUND	404	Task result not found
600006	TASK_EXPIRED	410	Task has expired
600007	TASK_CREATE_FAILED	500	Failed to create task

700xxx — Database

Code	Error Code	HTTP	Description
700001	DB_CONNECT_FAILED	500	Failed to connect to database
700002	DB_TIMEOUT	504	Database operation timed out
700003	DB_QUERY_FAILED	500	Database query execution failed

900xxx — System-Level Errors

Code	Error Code	HTTP	Description
900001	INTERNAL_ERROR	500	Internal server error
900003	SERVICE_UNAVAILABLE	503	Service unavailable
900005	DEPENDENCY_UNAVAILABLE	503	Required dependency unavailable

---

Retry Recommendations

Error Code Range	Retryable	Recommendation
100xxx, 400005	No	Fix the request parameters and resubmit
200xxx	Recommended	File download issues, backoff and retry
300xxx, 400xxx (except 400005)	Recommended	Service processing issues, backoff and retry
500xxx, 700xxx, 900xxx	Yes	Temporary service issues, retry with interval
600xxx	Depends	TASK_NOT_FOUND not retryable, timeout can recreate task
06001	No	Purchase a plan to continue
01xxx, 02xxx, 04xxx	No	Fix the file or parameters and retry