Exception Codes

Overview

The following are example business exception codes returned by gateway or business APIs. Field names may differ depending on the API: code, bizCode, errorCode, etc. Always refer to the specific API response for the exact field name. Implement branching logic based on the code value. 9999 indicates business success. All other non-success codes should be handled according to the scenario by retrying the request if appropriate, or correcting the request parameters before resubmission.

Relationship to HTTP status

The business code is usually carried in the JSON body; the HTTP status may still be 200. Always rely on the business code inside the response body.

Exception Code Reference

General

Code	Message	Description	Suggested action
0000	unknown exception	Unknown error	Log full request/response, retry; contact support if persistent
9999	SUCCESS	Success	Continue normal success flow

Validation & business (0001–0010)

Code	Message	Description	Suggested action
0001	Parameter exception!	Invalid or missing parameters	Verify required fields, types, length, and format against API docs
0002	signature verification failed!	Signature invalid	Check private key, signing string rules, and ensure sign is excluded from the string to sign; see Signature
0003	mch no channel available!	No channel available for merchant	Check amount/limits compliance; confirm channel activation and routing with ops / dashboard
0004	request duplicate!	Duplicate request	Use idempotency keys or merchant order number to deduplicate; avoid rapid resubmits
0005	order abnormality!	Order state inconsistent	Query order status before any retry; do not retry blindly
0006	the order does not exist!	Order not found	Verify order number and environment (sandbox vs production)
0007	Order payment method has been selected!	Payment method already chosen	Do not change channel again; continue or cancel and create a new order
0008	Order status abnormal!	Order status not allowed for this operation	Query order; only call APIs valid for the current status
0009	There is no payment method available for the order!	No payment method for this order	Check merchant/order supports the method and region configuration
0010	the bank does not exist!	Bank code invalid	Validate bank code against the documented bank list

Other & risk (1000–1003)

Code	Message	Description	Suggested action
1000	other exception!	Other error	Log context; retry or contact support
1001	ip whitelist exception!	IP not allowed	Add the egress IP to the merchant allowlist or contact support
1002	Insufficient balance!	Insufficient balance	Top up or reduce transaction amount
1003	amount exception	Amount invalid	Check currency rules, min/max limits, decimal places, and amount unit

Sample response (illustrative)

{
  "code": "0002",
  "message": "signature verification failed!",
  "data": null
}

Field names may differ per API—follow the endpoint documentation.

Related

• Signature