跳到主要内容

速率限制

为确保 PayerScan API 对所有商户的性能和可靠性，我们采用双重控制结构（Burst 和 Sustained）实施 API 速率限制。

限制范围​

速率限制按 API Key 应用。如果未提供 API Key，则按 IP 地址限制。这意味着：

  • 使用相同 API Key 的多台服务器共享同一限制。
  • 使用不同 API Key 的不同商店拥有独立的限制。

创建发票 API（POST /payment/crypto）​

限制类型阈值
Burst（最大瞬时）5 次请求 / 秒
Sustained60 次请求 / 分钟

查询发票 API（GET /invoice/:trans_id）​

限制类型阈值
Burst（最大瞬时）20 次请求 / 秒
Sustained200 次请求 / 分钟

超出限制时​

如果您的系统超过配置的阈值，API 将返回：

  • HTTP 状态码：429 Too Many Requests

超出 burst 限制（POST /payment/crypto）：

{
  "status": "error",
  "message": "Too many requests per second. Please slow down.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "limit_type": "burst",
  "retry_after_seconds": 1
}

超出 sustained 限制（POST /payment/crypto）：

{
  "status": "error",
  "message": "Rate limit exceeded. Maximum 60 requests per minute.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "limit_type": "sustained",
  "retry_after_seconds": 60
}
备注

message 和 retry_after_seconds 的值因端点不同而异。例如，GET 端点返回 "Maximum 200 requests per minute."，"retry_after_seconds": 60。

速率限制 Header​

API 在每个响应中返回标准速率限制 header：

Header描述
RateLimit-Limit当前窗口内允许的最大请求数。
RateLimit-Remaining当前窗口内剩余的请求数。
RateLimit-Reset速率限制窗口重置的时间（秒）。

使用这些 header 监控您的使用量，避免触及限制。

提示

在请求库中配置指数退避（Exponential Backoff）机制（如 Axios-retry），在遇到 HTTP 429 错误时自动按 retry_after_seconds 值等待后重试。