Standardized Format

All error responses follow a standardized format:

{
  "type": "error type",
  "code": "error code",
  "message": "error message"
}

1. Error Types

Error Type	HTTP Status Code	Scope	Remarks
invalid_request_error	400	invalid parameters
idempotence_error	400	idempotence request
account_error	400	house account sub account account product (metadata, restrict, auth trade)
api_error	500	any internal unexpected error	Contact technical support.
payment_error	400
refund_error	400
terminal_error	400

2. invalid_request_error

Error Code	Error Message	How to Fix
missing_parameter	Mandatory parameter is missing	Check whether all required request parameters are provided. Add any missing fields (e.g., amount, currency).
invalid_parameter	parameter is invalid	Verify the format and value range of the corresponding parameter.

3. idempotence_error

Error Code	Error Message	How to Fix
request_being_processed	request is being processed	Ensure requests are not sent too frequently, particularly within a short interval.
key_mismatch_account	key does not belong to account
key_mismatch_api	api associated with key is not the original	Request the original endpoint directly.
invalid_key_format	invalid idempotency key format	Using uuid v4

4. account_error

Error Code	Error Message	How to Fix
account_not_found	account not found or deactivated
sub_account_not_found	sub-account associated with the on-behalf-of not found or deactivated	Ensure the ID specified in the `x-on-behalf-of` header corresponds to a valid sub-account.
user_not_found	user associated with account not found or deactivated
product_not_found	product not found or inactive	Contact technical support.

5. payment_error

Error Code	Error Message	How to Fix
missing_billing_info	Missing billing info
missing_shipping_info	Missing shipping info
invalid_order_currency	Invalid order currency
invalid_order_amount	Invalid order amount
order_amount_too_small	Order amount is less than the minimum transaction amount	Adjust the order amount to meet the minimum limit required by the payment channel (e.g., ¥1.00); Contact customer support to confirm the exact threshold requirements.
amount_exceeded	Amount exceeded
count_exceeded	Count exceeded
avs_declined	AVS declined
invalid_payment_method	Invalid paymentmethod
invalid_billing_info_error	Invalid billing info
invalid_shipping_info	Invalid shipping info
payment_refused	Payment refused
invalid_card_number	Invalid Card Number
restricted_card	Restricted card	Try the transaction with a different card.
expired_card	Expired card
invalid_card_expire_date	Invalid card expire date
transtype_error	Transaction Typeerror
payment_rejected	Payment rejected by issuer	Prompt the user to contact their issuing bank to remove the restriction, or choose a different payment method.
abnormal_transaction	Abnormal transaction	Contact technical support.
expired_order	Expired order
closed_order	Closed order
issuer_unavailable	Issuer unavailable
not_enough_balance	Not enough balance
transaction_cancelled	Transaction cancelled
invalid_pin	Invalid Pin
pin_retry_exceeded	PIN tries exceeded
pin_validation_not_possible	PIN validation not possible
card_requires_online_pin	Card requires online pin
mobile_pin_required	Mobile PIN required
fraud	FRAUD
risk_reject	Reject by risk control
channel_parameters_error	Channel parameters error	Check wx mid, appid
transaction_already_reversed	Transaction was reversed
reversal_not_supported	Transaction does not support reversal
3ds_not_authenticated	3DS Not Authenticated
3ds_not_authenticated_error	3DS Authentication Error
3ds_not_authenticated_failed	3DS Authentication Failed
retrieve_payment_fail	Retrieve payment information error
order_conflict	Order number duplication
idempotency_violation	Channel Idempotency exception
invalid_refund_window	Exceeded the refund time limit
invalid_qr_code	QRC not found or status error
data_mismatch	The request data does not match the original order
system_error	System error
timeout	Timeout
operation_in_progress	The program is in progress.
signature_verify_fail	signature error
3DS_required	The issuer bank requires the 3D Secure process
invalid_encoding	The encoding format is incorrect
resource_not_found	Resource does not exists
invalid_cardholder_info	Cardholder identity information or mobile number incorrect
awaiting_user_input	Transaction has been redirected, waiting for cardholder input
internal_error	Internal Error: Please contact support for assistance	Contact technical support.
not_found_id	Not Found ID