Tất cả bài viết

Kiến trúc Phân bổ Hạn mức 2 Lớp & Ví Credit Dự phòng trên GoGoDuk

Phân tích kỹ thuật cơ chế rate limiting theo phút/ngày, tách biệt pool Sandbox vs Live, waterfall chuyển mạch sang Ví Credit dự phòng chống HTTP 429, cơ chế hoàn Credit khi lỗi 5xx và bộ response header giám sát.

Khi thiết kế một API bản đồ phục vụ các ứng dụng tại Việt Nam, bài toán kiểm soát lưu lượng (traffic control) luôn tồn tại hai trạng thái đối nghịch:

  1. Nhu cầu giới hạn cứng (Predictable Cap): Ứng dụng hoặc môi trường phát triển cần một ngưỡng ngày rõ ràng để tránh lỗi vòng lặp code hoặc bot bên ngoài đẩy lưu lượng vượt kiểm soát.
  2. Nhu cầu chống đứt gãy đột xuất (Spike Continuity): Trong môi trường production, lưu lượng thực tế không phân bổ đều — một chiến dịch vận hành hoặc khung giờ cao điểm có thể đẩy số request Live vượt hạn mức ngày trước thời điểm reset, dẫn đến lỗi HTTP 429 Too Many Requests.

Để giải quyết đồng thời hai yêu cầu này mà vẫn tách biệt hoàn toàn lưu lượng thử nghiệm khỏi lưu lượng thật, GoGoDuk tách cơ chế kiểm soát request thành hai lớp độc lập: Hạn mức ngày (Daily Quota Tiers) và Ví Credit Dự phòng (Failover Credit Wallet).


1. Kiến trúc Lớp 1: Hạn mức Ngày & Tách biệt Pool Sandbox vs Live

Mọi tài khoản trên GoGoDuk mặc định được cấp sẵn cấu hình Free, hoặc có thể mở rộng ngưỡng xử lý ngày thông qua hai mức Hỗ trợ hạ tầng (Infrastructure Support Tiers) chu kỳ 30 ngày (không tự động gia hạn).

Điểm quan trọng về mặt kỹ thuật là Live và Sandbox sử dụng hai bộ đếm (quota pool) tách biệt hoàn toàn, được reset độc lập tại 00:00 UTC (tương ứng 07:00 giờ Việt Nam):

Cấu hìnhChu kỳLive / ngàySandbox / ngàyBurst / phútSố API Key tối đa
Free (0đ)Vĩnh viễn100 req100 req60 req/phút10 keys
Starter (129.000đ)30 ngày350 req (~10.500/tháng)200 req60 req/phút10 keys
Pro (249.000đ)30 ngày750 req (~22.500/tháng)300 req60 req/phút10 keys

Tại sao phải tách riêng Sandbox Pool?

Trong thực tế vận hành, nhiều lỗi HTTP 429 trên production bắt nguồn từ việc môi trường staging, CI/CD integration test hoặc script benchmark của lập trình viên dùng chung hạn mức với ứng dụng thật. Khi tách riêng loại key SANDBOX:

  • Các request gắn key SANDBOX chỉ tiêu thụ vào hạn mức Sandbox ngày (100 / 200 / 300 req/ngày).
  • Kịch bản test tải hoặc lỗi vòng lặp trên môi trường dev không bao giờ làm cạn hạn mức Live và không bao giờ trừ vào số dư Ví Credit Dự phòng.

2. Kiến trúc Lớp 2: Ví Credit Dự phòng (Failover Credit Wallet)

Nếu Lớp 1 đóng vai trò cung cấp lưu lượng nền ổn định mỗi ngày, thì Lớp 2 (Failover Credit Wallet) đóng vai trò bộ đệm chống HTTP 429 RATE_LIMIT_DAY khi lưu lượng Live tăng đột biến.

Các đặc tính kỹ thuật của Ví Credit Dự phòng:

  • Quy đổi 1 Credit = 1 Live request: Không phụ thuộc gói ngày đang dùng (hoạt động bình thường ngay cả khi tài khoản đang ở cấu hình Free hoặc sau khi gói 30 ngày kết thúc chu kỳ).
  • Không hết hạn (Non-expiring): Số dư Credit tồn tại vĩnh viễn cho tới khi được tiêu thụ bởi lưu lượng Live thực tế vượt ngưỡng ngày.
  • Các mức mở Ví Credit qua chuyển khoản đồng hành hạ tầng (không lưu thẻ / không tự động trừ tiền):
    • C5K (Starter Pack) — 99.000đ: 5.000 Credits
    • C12K (Growth Pack) — 199.000đ: 12.000 Credits (bao gồm +2.000 bonus Credits, tương đương +20%)
    • C35K (Scale Pack) — 499.000đ: 35.000 Credits (bao gồm +10.000 bonus Credits, tương đương +40%)

3. Luồng Xử lý Waterfall & Nguyên tắc Bảo vệ An toàn

Mỗi request đi qua API Gateway của GoGoDuk được đánh giá theo thứ tự ưu tiên nghiêm ngặt sau:

Incoming Request
  │
  ├─► Route miễn trừ (GET /v1/usage) hoặc lỗi Auth (401 / 403)
  │     └─► Không trừ Daily Quota, không trừ Credit
  │
  ├─► Kiểm tra Burst Limit (60 req/phút mỗi key)
  │     └─► Vượt 60 req/phút ─► HTTP 429 (RATE_LIMIT_MINUTE) — KHÔNG dùng Credit
  │
  ├─► Key loại SANDBOX?
  │     ├─► Sandbox Quota > 0 ─► Trừ 1 Sandbox Quota ─► Thực thi
  │     └─► Sandbox Quota = 0 ─► HTTP 429 (RATE_LIMIT_DAY) — KHÔNG failover sang Credit
  │
  └─► Key loại LIVE
        ├─► Daily Live Quota > 0 ─► Trừ 1 Daily Live Quota (X-Quota-Source: daily)
        ├─► Daily Live Quota = 0 & Credit > 0 ─► Trừ 1 Credit (X-Quota-Source: credit)
        └─► Daily Live Quota = 0 & Credit = 0 ─► HTTP 429 (RATE_LIMIT_DAY)

Bảo vệ chống "đốt Credit" do lỗi client hoặc sự cố server

  1. Giới hạn phút (RATE_LIMIT_MINUTE = 60 req/phút) không đi qua Credit: Nếu một frontend React bị lỗi re-render vô hạn (infinite loop) và bắn 500 request trong vài giây, API Gateway sẽ chặn ngay tại lớp 60 req/phút trước khi chạm tới Ví Credit. Nhờ vậy, số dư Credit dự phòng không bị tiêu hao ngoài ý muốn do bug client.
  2. Tự động hoàn +1 Credit khi lỗi 5xx (X-Quota-Refunded: 1): Khi một request Live đã trừ 1 Credit (X-Quota-Source: credit) nhưng backend gặp sự cố trả về mã 5xx, hệ thống tự động cộng hoàn lại 1 Credit vào ví ngay trong vòng đời request đó và gắn header đánh dấu X-Quota-Refunded: 1.
  3. Miễn trừ cho lỗi xác thực và endpoint kiểm tra usage: Các phản hồi 401, 403 và lời gọi GET /v1/usage không bị tính vào hạn mức ngày lẫn Credit.

4. Giám sát qua HTTP Response Headers & Cảnh báo Tự động

Thay vì phải poll liên tục một endpoint khác để kiểm tra tình trạng hạn mức, mọi phản hồi API từ GoGoDuk đều trả về trực tiếp trạng thái quota và Credit tại HTTP headers:

HTTP/1.1 200 OK
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 58
X-RateLimit-Limit-Day: 350
X-RateLimit-Remaining-Day: 0
X-Quota-Source: credit
X-Credits-Remaining: 4912

Ý nghĩa các header chính:

  • X-Quota-Source: Cho biết request vừa rồi tiêu thụ từ nguồn nào — daily (hạn mức ngày) hay credit (đã chuyển mạch sang Ví Credit Dự phòng).
  • X-RateLimit-Remaining-Day: Số request còn lại trong hạn mức ngày hiện tại (tính đến 00:00 UTC). Khi giá trị này bằng 0 và X-Quota-Source: credit, hệ thống đang chạy bằng lớp dự phòng.
  • X-Credits-Remaining: Số dư Credit còn lại trong ví sau request.
  • X-Quota-Refunded: Xuất hiện với giá trị 1 nếu backend gặp lỗi 5xx và đã hoàn lại +1 Credit cho request đó.

Bên cạnh response headers, hệ thống gửi email cảnh báo tự động tại hai mốc 80% và 100% hạn mức ngày, kèm thông tin nhận biết ví Credit dự phòng có đang bảo vệ lưu lượng Live hay không để đội ngũ kỹ thuật kịp thời theo dõi.


5. Khuyến nghị Tích hợp phía Client (Backoff & Telemetry)

Khi tích hợp vào service backend hoặc SDK, ứng dụng nên phân tách cách xử lý header và mã lỗi 429 theo hai nhánh riêng biệt:

const res = await fetch(
  `https://api.gogoduk.com/v1/suggest?q=${encodeURIComponent(query)}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.GOGODUK_LIVE_KEY}`,
    },
  },
);
 
const quotaSource = res.headers.get("X-Quota-Source"); // "daily" | "credit"
const remainingDay = Number(res.headers.get("X-RateLimit-Remaining-Day") ?? 0);
const creditsRemaining = res.headers.get("X-Credits-Remaining");
const wasRefunded = res.headers.get("X-Quota-Refunded") === "1";
 
if (quotaSource === "credit") {
  console.info(
    `[GoGoDuk] Daily quota exhausted; running on failover credits. Remaining=${creditsRemaining}`,
  );
}
 
if (res.status === 429) {
  const err = await res.json().catch(() => ({}));
  if (err?.code === "RATE_LIMIT_MINUTE") {
    // Tạm dừng / exponential backoff vài giây vì vượt 60 req/phút
  } else if (err?.code === "RATE_LIMIT_DAY") {
    // Hết cả hạn mức ngày và Ví Credit dự phòng (chờ 00:00 UTC hoặc bổ sung hạn mức)
  }
}

Tóm tắt thiết kế

Việc tách biệt hạn mức ngày theo pool (Sandbox vs Live) và Ví Credit dự phòng không hết hạn giúp kiểm soát lưu lượng theo đúng ranh giới môi trường: dữ liệu thử nghiệm giữ ổn định trong Sandbox, lưu lượng nền vận hành trong trần ngày reset tại 00:00 UTC, và các đỉnh lưu lượng bất ngờ trên production được Ví Credit hấp thụ mà không trả về HTTP 429.

Muốn dùng GoGoDuk?

Bắt đầu với mức Free mặc định (100 Live + 100 Sandbox req/ngày), mở rộng hạn mức ngày qua mức Đồng hành hạ tầng Starter/Pro hoặc mở Ví Credit dự phòng không hết hạn.

Đăng ký →