错误码参考
响应格式
| 接口类型 | 响应格式 |
|---|---|
标准 API (/globalpay/v1/*) | JSON 结构化错误，包含 code、reason、message |
Webhook (/webhook/cactus) | 纯文本正文 + HTTP 状态码 |
全局规则
| 场景 | HTTP | reason | message |
|---|---|---|---|
| 内部错误 | 500 | INTERNAL SERVER ERROR | internal server error |
| 请求超时 | 504 | REQUEST_TIMEOUT | request timed out |
一、签名认证错误
| HTTP | reason | message |
|---|---|---|
| 400 | READ_BODY_ERROR | failed to read request body |
| 401 | MISSING_TRANSPORT | transport context not found |
| 401 | MISSING_API_KEY | X-Api-Key header required |
| 401 | MISSING_TIMESTAMP | X-Timestamp header required |
| 401 | MISSING_NONCE | X-Nonce header required |
| 401 | MISSING_SIGNATURE | X-Signature header required |
| 401 | INVALID_TIMESTAMP | timestamp parse/validation failure |
| 401 | TIMESTAMP_EXPIRED | timestamp outside allowed window |
| 401 | NONCE_ALREADY_USED | nonce replayed |
| 401 | INVALID_API_KEY | API key not found |
| 401 | API_KEY_DISABLED | API key is disabled |
| 401 | INVALID_SIGNATURE | signature verification failed |
| 401 | SIGNATURE_ERROR | non-structured signature verification error |
| 401 | AUTH_ERROR | lookup/auth internal failure |
二、GlobalPay 订单 API
2.1 创建订单 POST /globalpay/v1/orders
| HTTP | reason | message |
|---|---|---|
| 400 | INVALID_MERCHANT_ORDER_NO | merchant_order_no is required |
| 400 | INVALID_AMOUNT | amount must be a valid decimal number / amount must be greater than 0 |
| 400 | INVALID_AMOUNT_PRECISION | scientific notation is not supported / amount integer part is too large |
| 400 | ASSET_NOT_SUPPORTED | currency/chain not supported: {currency}/{chain} |
| 401 | MISSING_MERCHANT_ID | merchant authentication required |
| 429 | ORDER_BEING_PROCESSED | order is being created, please retry shortly |
| 429 | ADDRESS_POOL_EXHAUSTED | no available address in pool |
2.2 查询订单 GET /globalpay/v1/orders/{order_hash}
| HTTP | reason | message |
|---|---|---|
| 400 | ORDER_HASH_INVALID | order_hash is required / order_hash format is invalid |
| 404 | ORDER_NOT_FOUND | order not found |
order_hash 格式： ^[0-9a-fA-F]+-[0-9a-fA-F]{16}$
2.3 取消订单 POST /globalpay/v1/orders/{order_hash}/cancel
| HTTP | reason | message |
|---|---|---|
| 400 | ORDER_HASH_INVALID | order_hash is required / order_hash format is invalid |
| 400 | ORDER_NOT_CANCELLABLE | order status {n} cannot be cancelled |
| 401 | MISSING_MERCHANT_ID | merchant authentication required |
| 403 | FORBIDDEN | order does not belong to merchant |
| 404 | ORDER_NOT_FOUND | order not found |
| 429 | ORDER_OPERATION_IN_PROGRESS | an operation on this order is in progress, please retry |
三、GlobalPay 资产 API
GET /globalpay/v1/assets/supported
当前未定义专门的业务错误码，失败通常返回内部错误。
四、共享领域错误码
| HTTP | reason | message |
|---|---|---|
| 404 | MERCHANT_NOT_FOUND | merchant not found |
| 404 | API_KEY_NOT_FOUND | api key not found |
| 404 | SERVICE_ACCOUNT_NOT_FOUND | service account not found |
| 404 | SERVICE_ACCOUNT_API_KEY_NOT_FOUND | service account api key not found |
| 404 | ORDER_NOT_FOUND | order not found |
| 409 | ORDER_DUPLICATE | order already exists |
| 409 | CONCURRENT_UPDATE | concurrent update conflict, please retry |
| 429 | ADDRESS_POOL_EXHAUSTED | no available address in pool |
修改于 2026-05-11 05:22:28