Giới hạn tần suất

Giới hạn hiện tại

• Webhook BankOpenAPI gửi tới endpoint của bạn không tính vào giới hạn này.
• Bộ đếm chạy trên mạng lưới phân tán nên chỉ gần đúng: đôi khi cho qua quá mức một chút, đôi khi chặn sớm một chút. Đừng thiết kế hệ thống chạy sát ngưỡng.
• Response hiện chưa có header báo số request còn lại (kiểu X-RateLimit-Remaining).

Khi vượt giới hạn

API trả HTTP 429 kèm header Retry-After: 60 (số giây nên đợi):

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Quá nhiều request. Mỗi API key được gọi tối đa 100 request mỗi phút; đợi một lát rồi thử lại."
  }
}

Đợi ít nhất số giây trong Retry-After rồi gửi lại. Hàm dưới đây xử lý cả 429 lẫn lỗi 5xx:

// Gửi request, tự đợi và gửi lại khi gặp 429 hoặc lỗi 5xx (tối đa 4 lần)
async function callApi(url, options, attempt = 0) {
  const res = await fetch(url, options);
  const retryable = res.status === 429 || res.status >= 500;
  if (!retryable || attempt >= 3) return res;

  const retryAfter = Number(res.headers.get("retry-after")) || 0;
  const backoff = 2 ** attempt * 1000 + Math.random() * 500;
  await new Promise((r) => setTimeout(r, Math.max(retryAfter * 1000, backoff)));
  return callApi(url, options, attempt + 1);
}

Gọi API ít hơn

• Dùng webhook thay cho hỏi liên tục. Đừng gọi GET /v1/payment-requests/:id mỗi giây để chờ khách chuyển khoản; nhận payment_request.paid qua webhook.
• Trang thanh toán của bạn cần cập nhật trạng thái cho người trả thì để trình duyệt hỏi backend của bạn (đọc từ database đã được webhook cập nhật), không hỏi thẳng BankOpenAPI.
• Liệt kê với limit=100 để giảm số trang cần gọi.
• Nhiều hệ thống hay nhiều tiến trình dùng chung một khóa thì dùng chung giới hạn: tách khóa theo môi trường.