Error Codes (OpenAPI V2)

Top-level code (general)

• 0: success
• 400: invalid parameters or business error
• 401: invalid API key (auth failed)
• 403: no write permission (write APIs)
• 404: resource not found or no permission
• 429: rate limited
• 502: upstream service unavailable

Business error_code

When business errors occur, upstream may return error_code. OpenAPI V2 passes it through to top-level error_code (along with top-level code and message).

Note: if upstream returns a non-2xx response that cannot be parsed, you may only see HTTP-layer errors such as 404/502, and error_code may be absent.

Module error codes (100300 ~ 100329):

error_code	message	Description
100300	System error	System error (unclassified internal exception).
100301	Invalid request parameters	Invalid request parameters (missing required fields, wrong type, or illegal values).
100302	Unsupported version	Unsupported version (version cannot be recognized).
100303	Record not found	Record not found (record_id / record_url cannot locate a record).
100304	Form not found	Form not found (tpl_id cannot locate a form).
100305	Unsupported output format	Unsupported output format (format is invalid).
100306	Form not assigned to this code	The QR code is not associated with this form.
100307	Duplicate submission not allowed for this field	Duplicate submission not allowed (uniqueness check failed).
100308	Required field is empty	Required field is empty.
100309	Field validation failed	Field validation failed (format/content invalid).
100310	Submitted resource has expired	Dependent resource has expired.
100311	User submission limit reached	Per-user submission limit reached.
100312	Form submission limit reached	Form submission limit reached.
100313	Submission not allowed at current time	Submission is not allowed at current time.
100314	Submission not allowed in current code state	Submission is not allowed in current QR code state.
100315	API key invalid or disabled	API key is invalid or disabled.
100316	API key org mismatch	API key organization does not match request.
100317	No codes found in the selected category	No available QR codes in selected category.
100318	Too many codes found in the selected category	Too many QR codes matched (over system limit).
100319	Certificate verification failed	Generic certificate verification failure.
100320	Invalid certificate code	Invalid certificate code or target record not found.
100321	Certificate verification is not enabled	Verification is not enabled for the form/certificate.
100322	Certificate record is not approved for verification	Certificate record is not approved yet.
100323	Certificate does not match the requested scope	Certificate does not match tpl_id / code_id scope.
100324	Certificate cannot be verified in current status	Certificate cannot be verified in current status, or flow ended.
100325	Invalid verification action	Unsupported verification action or form configuration.
100326	Invalid target certificate status	Invalid target status, missing status, or no next status.
100327	Invalid verification authorization code	Verification authorization code invalid or expired.
100328	No permission to verify this certificate	Caller has no permission to verify this certificate.
100329	Identity information required before verification	Identity information must be completed before verification.