Skip to content

Common error codes

VellPay uses the response field code for the API call result. code=200 only indicates successful request processing; determine the final transaction result using data.status, an order query or callback.

Gateway authentication errors

Error codeError messageSuggested action
401Header country errorThe country cannot be identified from the domain or fallback request header; verify the country test domain
401Header appId is invalidCheck that appId belongs to the current environment and country and has the correct format and length
401Header timestamp not foundRequest headers are missing a valid 13-digit millisecond timestamp
401Header timestamp expireRequest time differs from platform time by more than five minutes; synchronize server time
401Nonce verify failnonce was reused or is invalid; generate a new random string
401authorization verification failedCheck the signing string, merchant private key, parameter sorting, and authorization
401app not set merchant public keyThe current application has no merchant public key; complete public-key exchange first
413json parse errorRequest body is not valid JSON
415body emptyRequest body is empty
416gateway maintainingGateway is under maintenance, retry later
500gateway errorInternal gateway error; record tid and contact VellPay technical support

Common business errors

Error codeError messageSuggested action
401signature verification failedSignature verification failed; regenerate the signature
412Please try again laterSystem is busy, retry later
413Request timestamp Timestamp timeoutRequest timestamp expired; use the current millisecond timestamp
414parameter validation failedParameter validation failed; see the field identified by msg
416Application not foundApplication does not exist; verify appId and the calling environment
417Merchant account not foundMerchant account does not exist or the country account is not enabled
418Merchant account is closedMerchant account is closed; contact technical support
421This payout method is not supportedThe current country does not support payoutType
423This payment method is not supportedThe current country does not support paymentType
424This payment method is not configuredThe merchant has not configured this pay-in method
425Insufficient merchant balanceThe merchant’s available balance is insufficient.
426merchant order duplicateMerchant order number is duplicated; check idempotency or use another order number
427The callback notification address for collection must not be empty.Configure a pay-in callback URL.
429The card number does not match the bank code.Bank account does not match the bank code
431The bank code does not supported.The current service does not support this bank code
433Payment way not support check outThe current payment method does not support checkout
434Merchant order not existMerchant order does not exist; check the order number and endpoint type
448request time outDownstream request timed out; query the original order before retrying
460The current payment method is unavailable.The current payment method is unavailable. Use another method or retry later.
462This request failed due to blacklist blockingRequest was blocked by the risk-control blacklist; check user parameters
466Payment method fee rate not configured.The merchant has not configured the payment-method fee rate
473Merchant joint verification errorMerchant country, account, payment method, or fee configuration is invalid
487This API has not yet been made available.The endpoint is not enabled for the current merchant or country
492The order amount does not fall within the configured amount range for the selected payment method.Order amount is outside the permitted payment-method range
500Business ErrorGeneral business error; record request details and tid, then contact technical support

Error response example

{
"code": 414,
"data": null,
"msg": "paymentType is invalid",
"tid": "747bbf80261844ed85b809212aab0d81"
}