Error Code

Common error codes (e.g. BAD_REQUEST / UNAUTHORIZED) are reused across multiple causes. The specific reason is conveyed via message / messageDetail — do not rely on code alone for branching.

Common Error Codes (All Endpoints - Signature Verification)

Error Code	HTTP Status	Description
BAD_REQUEST	400	Missing required headers
BAD_REQUEST	400	Invalid timestamp format
BAD_REQUEST	400	Timestamp out of allowed window
UNAUTHORIZED	401	Invalid app id
UNAUTHORIZED	401	App is not active
UNAUTHORIZED	401	Merchant is not active
FORBIDDEN	403	IP permission denied
UNAUTHORIZED	401	Invalid api secret
UNAUTHORIZED	401	Invalid signature
INTERNAL_SERVER_ERROR	500	Internal server error

---

Business Error Codes

createPayment - Create Payment Order

Error Code	Description
PAYMENT_GET_LOCK_ERROR	System is busy, please try again later
PAYMENT_DUPLICATE_ORDER	Order already exists
PAYMENT_INVALID_CONFIG	Merchant network configuration missing
PAYMENT_INVALID_CONFIG	No supported network found for currency
PAYMENT_INVALID_CONFIG	Receiving address not configured
PAYMENT_INVALID_CONFIG	Network must be specified for BGW payments
PAYMENT_INVALID_REQUEST	Network (payMethod2) is required when toAddress is provided
PAYMENT_INVALID_TO_ADDRESS	Invalid address format for network
PAYMENT_INVALID_PAY_METHOD	Invalid payment channel
PAYMENT_INVALID_PAY_METHOD	Payment network is required
PAYMENT_INVALID_PAY_METHOD	Please add a DeFi Wallet for {currency} on {network}

getPaymentStatus - Query Payment Status

Error Code	Description
PAYMENT_TRANSACTION_NOT_FOUND	Payment transaction not found

createRefund - Create Refund

Error Code	Description
PAYMENT_GET_LOCK_ERROR	System is busy, please try again later
PAYMENT_INVALID_PAYMENT_STATE	Payment state is not valid for refund
PAYMENT_DUPLICATE_REFUND	Duplicate refund transaction
PAYMENT_INVALID_REQUEST	Refund responsibility mismatch
PAYMENT_INVALID_REQUEST	Payment paidAmount is null
PAYMENT_INVALID_REQUEST	Refund amount exceeds paid amount
SYS_ERROR	Payment already refunded
SYS_ERROR	Unsupported payment method for refund
SYS_ERROR	Failed to create refund at payment channel
SYS_ERROR	Failed to create/update refund

getRefundStatus - Query Refund Status

Error Code	Description
PAYMENT_REFUND_NOT_FOUND	Refund transaction not found

trial - Get Exchange Rate Quote

Error Code	Description
UNSUPPORTED_CURRENCY_PAIR	Currency pair is not supported
UNSUPPORTED_CURRENCY_PAIR	Same currency conversion not allowed
UNSUPPORTED_CURRENCY_PAIR	Currency pair must be fiat <-> stablecoin
UNSUPPORTED_PAYMENT_CURRENCY	Payment currency is not supported by merchant
MERCHANT_QUOTE_RULE_NOT_FOUND	Merchant quote rule not found

Merchant Hierarchy (Partner Credentials)

Error Code	Description
MERCHANT_ID_REQUIRED	merchantId is required for partner credential
MERCHANT_APP_ID_REQUIRED	merchantAppId is required: multiple apps granted for this merchant
MERCHANT_GRANT_INVALID	No active grant covers the requested merchant
MERCHANT_STATE_INVALID	Target merchant is not active