Skip to main content

​
General Error Codes

Error CodeDescriptionApplicable APIHandling
400001Invalid request parametersGeneralCheck whether the request parameters are valid
400002Signature verification failedGeneralCheck the signature algorithm, signature string, and signing key. See Authentication and Security
400003Request timestamp expiredGeneralCheck the timestamp header
400007Unsupported Content-TypeGeneralCheck whether Content-Type meets API requirements
400020Invalid nonceGeneralCheck whether X-GatePay-Nonce is empty or malformed
400201Duplicate merchant order numberOrder-creation APIsCheck whether the same merchant order number was submitted repeatedly
400202Order not foundQuery APIsCheck whether the order number is correct
400204Invalid order statusOrder-operation APIsCheck whether the order is expired, cancelled, or closed
400603Order timed outPayment APIsConfirm whether the order has expired
400621Incorrect payment amountPayment APIsCheck the requested amount
400622Conversion failed due to exchange-rate fluctuationQuote / conversion APIsRetry if permitted by business flow
400624Invalid callback URLOrder-creation APIsCheck whether the callback URL is valid. See Notifications and Callbacks

​
Batch Payout Error Codes

For detailed payout error handling, see Payouts.
Error CodeDescriptionApplicable APIHandling
550233Insufficient balanceBatch payoutCheck available balance
550234Memo too longBatch payoutCheck memo length
550235Amount precision exceeds the allowed rangeBatch payoutCheck amount precision
550238Too many sub-ordersBatch payoutCheck the number of sub-orders
550239amount is missingBatch payoutProvide the amount field
550240currency is missingBatch payoutProvide the currency field
550241address is missingBatch payoutProvide the address field
550242chain is missingBatch payoutProvide the chain field
550245batch_id already existsBatch payoutUse a new batch_id or handle as idempotent
550249Invalid batch_id or withdraw_order_idBatch payoutCheck field format

​
Funds Ledger Query Error Codes

Error CodeDescriptionApplicable APIHandling
5504060Invalid orderType parameter (1=merchant order number, 2=GatePay order number, 3=funds ledger number)Funds ledger queryCorrect the orderType parameter
5504061Query size exceeds the limit (≤ 500)Funds ledger queryReduce the number of records requested per call

​
QR Payment Error Codes

Error CodeDescriptionApplicable APIHandling
400000Invalid request formatQR paymentCheck request data format
400002Signature verification failedQR paymentCheck whether the merchant signature is correct. See Authentication and Security
400003Request timestamp expiredQR paymentCheck the timestamp header
400007Unsupported media typeQR paymentCheck the API Content-Type
400603Order timed outQR paymentConfirm whether the order has expired
400621Incorrect payment amountQR paymentCheck the requested amount
400620Duplicate payment orderQR paymentCheck whether the merchant order number was submitted repeatedly
500008Merchant not foundQR paymentCheck whether the merchant ID is correct
500100Payment QR code has expiredQR paymentCreate a new order to generate a new QR code
500101Duplicate QR paymentQR paymentVerify the order status

​
Web Payment Error Codes

Error CodeDescriptionApplicable APIHandling
300000System errorWeb paymentRetry with the same parameters
300001System errorWeb paymentRetry with the same parameters
400000Unknown errorWeb paymentRecord the request, retry, or contact support
400001Invalid request parameter formatWeb paymentCheck the request parameters and data format
400002Signature verification failedWeb paymentCheck whether the merchant signature is correct. See Authentication and Security

​
Best Practices

​
Callback and Query Fallback Strategy

Use a “callbacks first, query as fallback” confirmation model for reliable order status management: Recommended approach:
  1. Rely on callbacks as the primary notification mechanism (see Notifications and Callbacks for integration details)
  2. Implement signature verification before processing any callback (see Authentication and Security)
  3. Use idempotency to handle duplicate callbacks safely
  4. Store notifications durably before processing
  5. Implement state-machine control for callback processing
Fallback Query Strategy: If callbacks are missing or delayed, use progressive backoff for status queries:
  • 5 seconds
  • 10 seconds
  • 30 seconds
  • 1 minute
  • 3 minutes
  • 5 minutes
This strategy prevents overwhelming the API while ensuring timely order confirmation.

​
Refund Confirmation

Refunds are asynchronous operations. A successful refund API response indicates only that the request has been accepted; it does not confirm the refund was actually processed. Required practice:
  • Confirm final refund results through the refund query API or refund callback (see Payments for refund callback details)
  • Use the “callbacks first, query as fallback” pattern to verify refund completion
  • Never consider a refund complete based solely on the API response

​
Security Best Practices

Authentication and Signature Verification
  • Always verify callback signatures before processing (see Authentication and Security)
  • Never return SUCCESS in a callback response if signature verification fails
  • Check the request timestamp to prevent replay attacks
Key Management
  • Do not expose server-side signing keys or credentials in client applications
  • Store merchant secrets securely using environment variables or secure vaults
  • Rotate signing keys periodically and maintain separate keys for test and production environments
Request Validation
  • Validate all request parameters before processing
  • Check Content-Type headers and ensure they match API requirements
  • Use HTTPS with TLS 1.2+ for all API communications