跳转到主要内容

​
通用错误码

错误码说明适用 API处理方式
400001请求参数非法通用检查请求参数是否有效
400002Signature verification failedGeneralCheck the signature algorithm, signature string, and signing key. See 认证与安全
400003请求时间戳已过期通用检查时间戳请求头
400007不支持的 Content-类型通用检查 Content-类型 是否符合 API 要求
400020nonce 非法通用检查 X-GatePay-Nonce 是否为空或格式错误
400201商户订单号重复创建订单相关 API检查是否重复提交了相同商户订单号
400202订单不存在查询类 API检查订单号是否正确
400204订单状态非法订单操作类 API检查订单是否已过期、取消或关闭
400603Order timed out支付 APIConfirm whether the 订单 has expired
400621Incorrect payment amount支付 APICheck the requested amount
400622因汇率波动导致兑换失败报价 / 兑换类 API如业务流程允许，可重试
400624Invalid 回调 URLOrder-creation APIsCheck whether the 回调 URL is valid. See 通知与回调

​
批量出款错误码

For detailed 出款 error handling, see 出款.
错误码说明适用 API处理方式
550233Insufficient balanceBatch 出款Check available balance
550234Memo too longBatch 出款Check memo length
550235Amount precision exceeds the allowed rangeBatch 出款Check amount precision
550238Too many sub-订单sBatch 出款Check the number of sub-订单s
550239amount is missingBatch 出款Provide the amount field
550240currency is missingBatch 出款Provide the currency field
550241address is missingBatch 出款Provide the address field
550242chain is missingBatch 出款Provide the chain field
550245batch_id already existsBatch 出款Use a new batch_id or handle as idempotent
550249Invalid batch_id or withdraw_订单_idBatch 出款Check field format

​
资金流水查询 错误码

错误码说明适用 API处理方式
5504060Invalid 订单类型 parameter (1=商户 订单 number, 2=GatePay 订单 number, 3=资金 账本 number)Funds 账本 queryCorrect the 订单类型 parameter
5504061Query size exceeds the limit (≤ 500)Funds 账本 queryReduce the number of records requested per call

​
QR Payment 错误码

错误码说明适用 API处理方式
400000Invalid request formatQR paymentCheck request data format
400002Signature verification failedQR paymentCheck whether the 商户 signature is correct. See 认证与安全
400003请求 timestamp expiredQR paymentCheck the timestamp header
400007Unsupported media typeQR paymentCheck the API Content-类型
400603Order timed outQR paymentConfirm whether the 订单 has expired
400621Incorrect payment amountQR paymentCheck the requested amount
400620Duplicate payment 订单QR paymentCheck whether the 商户 订单 number was submitted repeatedly
500008商户 not foundQR paymentCheck whether the 商户 ID is correct
500100Payment QR code has expiredQR paymentCreate a new 订单 to generate a new QR code
500101Duplicate QR paymentQR paymentVerify the 订单 status

​
Web Payment 错误码

错误码说明适用 API处理方式
300000System errorWeb paymentRetry with the same parameters
300001System errorWeb paymentRetry with the same parameters
400000Unknown errorWeb paymentRecord the request, 重试, or contact support
400001Invalid request parameter formatWeb paymentCheck the request parameters and data format
400002Signature verification failedWeb paymentCheck whether the 商户 signature is correct. See 认证与安全

​
最佳实践

​
回调 and Query Fallback Strategy

Use a “回调s first, query as fallback” confirmation model for reliable 订单 status management: Recommended approach:
  1. Rely on 回调s as the primary 通知 mechanism (see 通知与回调 for integration details)
  2. Implement signature verification before processing any 回调 (see 认证与安全)
  3. Use 幂等性 to handle duplicate 回调s safely
  4. Store 通知s durably before processing
  5. Implement state-machine control for 回调 processing
Fallback Query Strategy: If 回调s 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 订单 confirmation.

​
Re资金 Confirmation

Re资金 are 异步 operations. A successful re资金 API response indicates only that the request has been accepted; it does not confirm the re资金 was actually processed. 必填 practice:
  • Confirm final re资金 results through the re资金 query API or re资金 回调 (see 支付 for re资金 回调 details)
  • Use the “回调s first, query as fallback” pattern to verify re资金 completion
  • Never consider a re资金 complete based solely on the API response

​
Security 最佳实践s

Authentication and Signature Verification
  • Always verify 回调 signatures before processing (see 认证与安全)
  • Never return SUCCESS in a 回调 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 应用s
  • Store 商户 secrets securely using environment variables or secure vaults
  • Rotate signing keys periodically and maintain separate keys for test and production environments
请求 Validation
  • Validate all request parameters before processing
  • Check Content-类型 headers and ensure they match API requirements
  • Use HTTPS with TLS 1.2+ for all API communications
  • 支付 — Payment processing and re资金 handling
  • 出款 — 出款 error codes and handling
  • 通知与回调 — 回调 integration patterns
  • 认证与安全 — Signature verification and security practices