> ## 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](/global/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](/global/essentials/version/100/en/inflow/payment/payment) | Confirm whether the order has expired |
| 400621 | Incorrect payment amount | [Payment APIs](/global/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](/global/essentials/version/100/en/common/notification) |

***

## Batch Payout Error Codes

For detailed payout error handling, see [Payout](/global/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](/global/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](/global/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](/global/essentials/version/100/en/common/notification) for integration details)
2. **Implement signature verification** before processing any callback (see [Authentication and Security](/global/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](/global/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](/global/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](/global/essentials/version/100/en/inflow/payment/payment) — Payment processing and refund handling
* [Payout](/global/essentials/version/100/en/outflow/payout) — Payout error codes and handling
* [Notifications and Callbacks](/global/essentials/version/100/en/common/notification) — Callback integration patterns
* [Authentication and Security](/global/essentials/version/100/en/common/authentication) — Signature verification and security practices


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.