Error Codes

When an API call fails, the response contains a non-zero code and a message describing the failure:

{
  "code": 2080010,
  "message": "user not found in search",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": {}
}

Field	Description
code	Business error code. 0 = success; non-zero = failure
message	Human-readable error description
requestId	Unique request ID — always record it for troubleshooting

HTTP Status Codes

HTTP Code	Meaning	Recommendation
200	Request reached the business layer	Check the code field in the body for the real result
401	Unauthorized	Check the Authorization header and API Key validity
403	Forbidden	Check whether the application is disabled or the credential revoked
429	Too many requests	Reduce QPS — the default limit is 20 req/sec; contact the official team to request a higher limit
5xx	Server error	Retry later; contact support with the requestId if it persists

Business Error Codes

Business error codes are 7-digit decimals: the first 3 digits identify the module, the last 4 the specific error. Three segments are involved:

• 1000xxx — generic errors (parameter validation, internal failures)
• 2060xxx — credential/authentication errors (gateway layer)
• 2080xxx — palmprint business errors

Generic (1000xxx)

Code	Message	Meaning / Recommendation
0	ok	Success
1000000	invalid param	Parameter validation failed (missing required field, illegal format, length exceeded). Check the request against the interface's parameter table
1000001	internal error	Internal server error. Retry later; contact support with the requestId if it persists
1000011	database operation failed	Database operation failed. Retry later; report with the requestId if reproducible
1000013	forbidden	Operation not permitted (application disabled or credential revoked). Check application status in the console

Credential & Authentication (2060xxx)

Returned at the gateway before any business logic runs.

Code	Message	Meaning / Recommendation
2060000	unauthorized	Missing Authorization header, or the API Key is invalid/expired. Verify the header format and credential
2060002	too many requests	Rate limit exceeded (default: 20 req/sec). Lower your QPS, or contact the official team to request a higher limit
2060200	openapi credential not found	Credential does not exist (may have been deleted). Confirm in the console or regenerate
2060202	openapi credential revoked	Credential has been revoked. Regenerate it in the console
2060203	openapi credential invalid	Malformed credential or signature check failed. Verify the API Key was copied in full
2060204	openapi credential type invalid	Wrong credential type — the value after Bearer must carry the ak_ prefix
2060207	OpenAPI app not configured	The application is not configured on the platform. Contact support

Palmprint Business (2080xxx)

Code	Message	Meaning / Recommendation
2080000	no available version	No available algorithm version. Contact support to confirm product provisioning
2080001	unknown image type	Unknown image type. Ensure RgbImage.Data is a valid Base64-encoded JPEG/PNG and ImageType is 1
2080002	image MD5 mismatch	Image data corrupted or truncated in transit. Retry from the client
2080003	liveness check failed	Liveness check failed (possible photo/replay attack). Guide the user to recapture a real palm
2080004	quality check failed	Image quality check failed (blurry, incomplete palm, poor lighting). Guide the user to recapture
2080007	already bound	A palmprint already exists for this UserId + PalmDirection. Set IsForce=true in RegisterRgbPalm to overwrite
2080009	data not found	Data not found. The specified UserId/PalmDirection has no registered palmprint
2080010	user not found in search	SearchRgbPalm matched no user in the gallery. Normal business result, not a system error
2080011	table capacity full	Gallery partition capacity full. Contact support for expansion
2080014	palm capacity full	Application palmprint capacity reached. Delete unused palmprints, or contact the official team to request an expansion
2080016	user does not exist in DB	User does not exist. Register via RegisterRgbPalm before compare/delete operations
2080017	user palm direction does not exist in DB	No palmprint for the specified palm direction. Check PalmDirection or register first
2080018	concurrent operation in DB, please retry	Concurrent operation conflict. Retry with backoff; avoid parallel register/delete calls for the same user
2080020	palm capacity quota exceeded	Platform feature quota exceeded. Contact support to expand capacity
2080023	app does not exist	Application does not exist. Verify the application bound to your API Key
2080024	compare session expired or not exist	The SessionId from a comparison does not exist or has expired (valid for 2 hours). Re-run CompareRgbPalm

📌 Troubleshooting tips

• Always keep the requestId — it is the key clue for official support.
• 1:N searches returning 2080010 and duplicate registrations returning 2080007 are normal business outcomes, not system failures.
• If you repeatedly hit capacity errors (2080011, 2080014, 2080020) or 2060002, contact the official team with your requestId to request a higher limit or capacity expansion.