跳到主要内容

错误代码

PayerScan API 使用标准化的错误响应格式。所有错误遵循一致的结构，便于商户后端处理。

错误响应结构​

{
  "status": "error",
  "message": "Invalid API key. Please check your API key and try again.",
  "error_code": "INVALID_API_KEY",
  "request_id": "ORDER_123456",
  "details": { ... }
}

属性说明：

  • status：始终为 "error"。
  • message：人类可读的错误描述。
  • error_code：机器可读的错误代码，UPPER_SNAKE_CASE 格式。使用 switch/case 自动处理。
  • request_id （可选）：您的订单 ID，仅在创建发票时提供后返回。
  • details （可选）：错误的附加上下文（如验证错误、字段名称）。

错误代码参考​

认证错误​

错误代码HTTPMessage解决方案
MISSING_API_KEY401Missing API key. Please provide x-api-key header.在请求中添加 x-api-key header。
INVALID_API_KEY401Invalid API key. Please check your API key and try again.在 Dashboard 上验证您的 API key。
ACCOUNT_INACTIVE403Merchant account is inactive. Please contact support to reactivate.联系 PayerScan 支持。
STORE_INACTIVE403Store is inactive. Please contact support to reactivate your store.在 Dashboard 上重新启用商店。
AUTHENTICATION_FAILED500Authentication failed. Please try again later.稍后重试；如果持续出现，请联系支持。

验证错误​

错误代码HTTPMessage解决方案
VALIDATION_ERROR400Validation failed. Please check your request body.检查 details.errors 了解具体字段问题。
INVALID_MERCHANT_ID400Invalid merchant_id. The merchant_id does not match your API key.确保 merchant_id 与 API key 的商店匹配。

业务逻辑错误​

错误代码HTTPMessage解决方案
INSUFFICIENT_BALANCE402Insufficient balance. Please top-up your account to continue.在 PayerScan Dashboard 充值。查看 details 了解缺少金额。
NO_PAYMENT_METHOD400No payment method configured. Please add at least one wallet or exchange platform.在 Dashboard 上添加钱包或连接交易所平台。

发票错误​

错误代码HTTPMessage解决方案
INVOICE_NOT_FOUND404Invoice not found.验证 trans_id 并确保属于您的商店。
MISSING_TRANS_ID400Missing trans_id in URL.在 URL 路径中包含 trans_id：GET /invoice/:trans_id。
INVALID_TRANS_ID_FORMAT400Invalid trans_id format.使用正确格式：TID-XXXXXXXXXXXXXXXX。

速率限制错误​

错误代码HTTPMessage解决方案
RATE_LIMIT_EXCEEDED429Too many requests per second. / Rate limit exceeded.等待 retry_after_seconds 后重试。参见速率限制。

服务器错误​

错误代码HTTPMessage解决方案
INTERNAL_ERROR500Internal server error. Please try again later.使用指数退避重试。如果持续出现，请联系支持。