Error - Gate Pay DOCS

General Error Codes

Error Code	Description	Applicable API	Handling
400001	Invalid request parameters	General	Check whether the request parameters are valid
400002	Signature verification failed	General	Check the signature algorithm, signature string, and signing key. See Authentication and Security
400003	Request timestamp expired	General	Check the timestamp header
400007	Unsupported Content-Type	General	Check whether Content-Type meets API requirements
400020	Invalid nonce	General	Check whether X-GatePay-Nonce is empty or malformed
400201	Duplicate merchant order number	Order-creation APIs	Check whether the same merchant order number was submitted repeatedly
400202	Order not found	Query APIs	Check whether the order number is correct
400204	Invalid order status	Order-operation APIs	Check whether the order is expired, cancelled, or closed
400603	Order timed out	Payment APIs	Confirm whether the order has expired
400621	Incorrect payment amount	Payment APIs	Check the requested amount
400622	Conversion failed due to exchange-rate fluctuation	Quote / conversion APIs	Retry if permitted by business flow
400624	Invalid callback URL	Order-creation APIs	Check whether the callback URL is valid. See Notifications and Callbacks

Batch Payout Error Codes

For detailed payout error handling, see Payout.

Error Code	Description	Applicable API	Handling
550233	Insufficient balance	Batch payout	Check available balance
550234	Memo too long	Batch payout	Check memo length
550235	Amount precision exceeds the allowed range	Batch payout	Check amount precision
550238	Too many sub-orders	Batch payout	Check the number of sub-orders
550239	amount is missing	Batch payout	Provide the amount field
550240	currency is missing	Batch payout	Provide the currency field
550241	address is missing	Batch payout	Provide the address field
550242	chain is missing	Batch payout	Provide the chain field
550245	batch_id already exists	Batch payout	Use a new batch_id or handle as idempotent
550249	Invalid batch_id or withdraw_order_id	Batch payout	Check field format

Funds Ledger Query Error Codes

Error Code	Description	Applicable API	Handling
5504060	Invalid orderType parameter (1=merchant order number, 2=GatePay order number, 3=funds ledger number)	Funds ledger query	Correct the orderType parameter
5504061	Query size exceeds the limit (≤ 500)	Funds ledger query	Reduce the number of records requested per call

QR Payment Error Codes

Error Code	Description	Applicable API	Handling
400000	Invalid request format	QR payment	Check request data format
400002	Signature verification failed	QR payment	Check whether the merchant signature is correct. See Authentication and Security
400003	Request timestamp expired	QR payment	Check the timestamp header
400007	Unsupported media type	QR payment	Check the API Content-Type
400603	Order timed out	QR payment	Confirm whether the order has expired
400621	Incorrect payment amount	QR payment	Check the requested amount
400620	Duplicate payment order	QR payment	Check whether the merchant order number was submitted repeatedly
500008	Merchant not found	QR payment	Check whether the merchant ID is correct
500100	Payment QR code has expired	QR payment	Create a new order to generate a new QR code
500101	Duplicate QR payment	QR payment	Verify the order status

Web Payment Error Codes

Error Code	Description	Applicable API	Handling
300000	System error	Web payment	Retry with the same parameters
300001	System error	Web payment	Retry with the same parameters
400000	Unknown error	Web payment	Record the request, retry, or contact support
400001	Invalid request parameter format	Web payment	Check the request parameters and data format
400002	Signature verification failed	Web payment	Check 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:

Rely on callbacks as the primary notification mechanism (see Notifications and Callbacks for integration details)
Implement signature verification before processing any callback (see Authentication and Security)
Use idempotency to handle duplicate callbacks safely
Store notifications durably before processing
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

Payments — Payment processing and refund handling
Payout — Payout error codes and handling
Notifications and Callbacks — Callback integration patterns
Authentication and Security — Signature verification and security practices

​General Error Codes

​Batch Payout Error Codes

​Funds Ledger Query Error Codes

​QR Payment Error Codes

​Web Payment Error Codes

​Best Practices

​Callback and Query Fallback Strategy

​Refund Confirmation

​Security Best Practices

​Related Documentation