Giới hạn tốc độ

Để đảm bảo hiệu suất và độ tin cậy của PayerScan API cho tất cả merchant, chúng tôi áp dụng giới hạn tốc độ API với cơ chế kiểm soát kép (Burst và Sustained).

Phạm vi giới hạn

Giới hạn tốc độ được áp dụng theo API Key. Nếu không có API Key, giới hạn sẽ tính theo địa chỉ IP. Điều này có nghĩa:

• Nhiều server dùng cùng API Key chia sẻ chung giới hạn.
• Các store khác nhau với API Key khác nhau có giới hạn độc lập.

API tạo hóa đơn (POST /payment/crypto)

Loại giới hạn	Ngưỡng
Burst (tức thời tối đa)	5 request / giây
Sustained	60 request / phút

API tra cứu hóa đơn (GET /invoice/:trans_id)

Loại giới hạn	Ngưỡng
Burst (tức thời tối đa)	20 request / giây
Sustained	200 request / phút

Khi vượt giới hạn

Nếu hệ thống của bạn vượt ngưỡng cho phép, API sẽ trả về:

• HTTP Status Code: 429 Too Many Requests

Vượt giới hạn 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
}

Vượt giới hạn 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
}

ghi chú

Giá trị message và retry_after_seconds thay đổi tùy endpoint. Ví dụ, endpoint GET trả về "Maximum 200 requests per minute." với "retry_after_seconds": 60.

Header giới hạn tốc độ

API trả về các header giới hạn tốc độ chuẩn trong mỗi response:

Header	Mô tả
RateLimit-Limit	Số request tối đa cho phép trong window hiện tại.
RateLimit-Remaining	Số request còn lại trong window hiện tại.
RateLimit-Reset	Thời gian (giây) cho đến khi window giới hạn reset.

Sử dụng các header này để theo dõi mức sử dụng và tránh vượt ngưỡng.

mẹo

Cấu hình cơ chế Exponential Backoff trong thư viện request (ví dụ: Axios-retry) để tự động retry sau giá trị retry_after_seconds khi gặp lỗi HTTP 429.