Rate Limits

To ensure the performance and reliability of the PayerScan API for all merchants, we enforce API rate limits with a dual-control structure (Burst and Sustained).

Rate Limit Scope

Rate limits are applied per API Key. If your API Key is not provided, the limit falls back to your IP address. This means:

• Multiple servers using the same API Key share the same rate limit.
• Different stores with different API Keys have independent limits.

Create Invoice API (POST /payment/crypto)

Limit Type	Threshold
Burst (max instant)	5 requests / second
Sustained	60 requests / minute

Invoice Lookup API (GET /invoice/:trans_id)

Limit Type	Threshold
Burst (max instant)	20 requests / second
Sustained	200 requests / minute

When Limits Are Exceeded

If your system exceeds the configured threshold, the API will return:

• HTTP Status Code: 429 Too Many Requests

Burst limit exceeded (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 limit exceeded (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
}

note

The message and retry_after_seconds values vary by endpoint. For example, the GET endpoint returns "Maximum 200 requests per minute." with "retry_after_seconds": 60.

Rate Limit Headers

The API returns standard rate limit headers with every response:

Header	Description
RateLimit-Limit	Maximum number of requests allowed in the current window.
RateLimit-Remaining	Number of requests remaining in the current window.
RateLimit-Reset	Time (in seconds) until the rate limit window resets.

Use these headers to monitor your usage and avoid hitting the limits.

tip

Configure an Exponential Backoff mechanism in your request library (e.g., Axios-retry) to automatically retry after the retry_after_seconds value when encountering an HTTP 429 error.