> ## Documentation Index > Fetch the complete documentation index at: https://docs.gate.com/llms.txt > Use this file to discover all available pages before exploring further. # Error > This guide covers GatePay API error codes and recommended practices for handling errors, callbacks, and asynchronous operations. ## 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](/essentials/version/100/en/common/authentication) | | 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](/essentials/version/100/en/inflow/payment/payment) | Confirm whether the order has expired | | 400621 | Incorrect payment amount | [Payment APIs](/essentials/version/100/en/inflow/payment/payment) | 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](/essentials/version/100/en/common/notification) | *** ## Batch Payout Error Codes For detailed payout error handling, see [Payout](/essentials/version/100/en/outflow/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](/essentials/version/100/en/common/authentication) | | 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](/essentials/version/100/en/common/authentication) | *** ## 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](/essentials/version/100/en/common/notification) for integration details) 2. **Implement signature verification** before processing any callback (see [Authentication and Security](/essentials/version/100/en/common/authentication)) 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](/essentials/version/100/en/inflow/payment/payment) 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](/essentials/version/100/en/common/authentication)) * 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 *** ## Related Documentation * [Payments](/essentials/version/100/en/inflow/payment/payment) — Payment processing and refund handling * [Payout](/essentials/version/100/en/outflow/payout) — Payout error codes and handling * [Notifications and Callbacks](/essentials/version/100/en/common/notification) — Callback integration patterns * [Authentication and Security](/essentials/version/100/en/common/authentication) — Signature verification and security practices