All posts

Two-Layer Quota Allocation and Non-Expiring Failover Credit Wallet Architecture

Technical deep dive into GoGoDuk's per-minute/daily rate limiting, isolated Sandbox vs Live quota pools, automatic Failover Credit Wallet switching against HTTP 429, 5xx auto-refunds, and telemetry response headers.

Designing rate limits for a production Vietnam geocoding and address API involves resolving two competing operational constraints:

  1. Bounded Daily Predictability: Development environments and standard workloads need deterministic daily ceilings so client-side bugs or unexpected scraper traffic cannot cause runaway resource consumption.
  2. Spike Continuity on Live Traffic: Real-world production workloads rarely distribute evenly across 24 hours. A dispatch surge or regional campaign can exhaust the daily cap before reset time, causing HTTP 429 Too Many Requests errors unless a failover buffer exists.

To satisfy both requirements without mixing test traffic into production budgets, GoGoDuk implements a two-layer quota engine: fixed Daily Quota Tiers paired with a non-expiring Failover Credit Wallet.


1. Layer 1: Daily Quota Tiers & Isolated Sandbox vs Live Pools

Every GoGoDuk account starts on the Free configuration and can optionally expand its daily ceilings via 30-day Infrastructure Support Tiers (manual renewal, with zero automatic recurring charges).

Crucially, Live and Sandbox API keys draw from completely separate counters, each resetting daily at 00:00 UTC (07:00 ICT):

ConfigurationCycleLive / daySandbox / dayPer-minute burstMax API keys
Free (0đ)Forever100 req100 req60 req/min10 keys
Starter (129,000 VND)30 days350 req (~10,500/mo)200 req60 req/min10 keys
Pro (249,000 VND)30 days750 req (~22,500/mo)300 req60 req/min10 keys

Why isolate Sandbox from Live?

Many unexpected production HTTP 429 outages happen when CI pipelines, staging servers, or benchmark scripts share a quota bucket with Live application traffic. Enforcing separate pool accounting guarantees:

  • Requests authenticated with a SANDBOX key consume strictly from the daily Sandbox pool (100 / 200 / 300 req/day).
  • Staging load tests or accidental infinite loops in local development cannot exhaust Live daily quota and never touch the Failover Credit Wallet.

2. Layer 2: Non-Expiring Failover Credit Wallet

While Layer 1 defines steady-state daily capacity, Layer 2 (Failover Credit Wallet) acts as an automatic circuit absorber against HTTP 429 RATE_LIMIT_DAY whenever Live requests exceed the daily ceiling.

Core architectural properties:

  • 1 Credit = 1 Live request: Works independently of the active daily tier (including accounts on Free or after a 30-day Starter/Pro period ends).
  • Non-expiring balance: Credits remain available indefinitely until consumed by Live overflow traffic.
  • Failover Credit tiers via voluntary bank transfer (no stored cards or auto-rebilling):
    • C5K (Starter Pack) — 99,000 VND: 5,000 Credits
    • C12K (Growth Pack) — 199,000 VND: 12,000 Credits (includes +2,000 / +20% bonus Credits)
    • C35K (Scale Pack) — 499,000 VND: 35,000 Credits (includes +10,000 / +40% bonus Credits)

3. Waterfall Evaluation Order & Abuse Safeguards

Every API call entering the GoGoDuk Gateway passes through a deterministic evaluation pipeline:

Incoming Request
  │
  ├─► Exempt route (GET /v1/usage) or Auth failure (401 / 403)
  │     └─► No Daily Quota or Credit deduction
  │
  ├─► Per-Minute Rate Limiter (60 req/min per key)
  │     └─► > 60 req/min ─► HTTP 429 (RATE_LIMIT_MINUTE) — Credits NOT used
  │
  ├─► SANDBOX API Key?
  │     ├─► Sandbox Quota > 0 ─► Deduct 1 Sandbox Quota ─► Execute
  │     └─► Sandbox Quota = 0 ─► HTTP 429 (RATE_LIMIT_DAY) — NO failover to Credits
  │
  └─► LIVE API Key
        ├─► Daily Live Quota > 0 ─► Deduct 1 Daily Quota (X-Quota-Source: daily)
        ├─► Daily Live Quota = 0 & Credits > 0 ─► Deduct 1 Credit (X-Quota-Source: credit)
        └─► Daily Live Quota = 0 & Credits = 0 ─► HTTP 429 (RATE_LIMIT_DAY)

Guardrails against unintended Credit drain

  1. Per-minute throttling (RATE_LIMIT_MINUTE = 60 req/min) stays outside Credit failover: If a client frontend hits a render loop firing hundreds of requests per second, the 60 req/min ceiling drops excess calls immediately before reaching the Credit ledger, protecting your backup balance.
  2. Automatic +1 Credit refund on 5xx errors (X-Quota-Refunded: 1): If a request consumes a Failover Credit (X-Quota-Source: credit) and the upstream handler fails with a 5xx status code, the gateway automatically credits +1 back within the request lifecycle and flags X-Quota-Refunded: 1.
  3. Non-deductible system traffic: GET /v1/usage polling and invalid-auth responses (401/403) never consume quota or Credits.

4. Real-Time Observability via HTTP Headers & Alerts

Rather than forcing clients to make extra telemetry requests before every batch, GoGoDuk embeds current rate-limit and failover state directly in HTTP response 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

Header semantics:

  • X-Quota-Source: Indicates which bucket served the request — daily (daily quota tier) or credit (Failover Credit Wallet).
  • X-RateLimit-Remaining-Day: Remaining requests in today's daily quota pool (until 00:00 UTC). Seeing 0 alongside X-Quota-Source: credit confirms failover is active.
  • X-Credits-Remaining: Updated Failover Credit balance after this request.
  • X-Quota-Refunded: Present with value 1 when a 5xx failure triggered an automatic +1 Credit refund.

In addition to per-request headers, automated email alerts trigger at 80% and 100% of the daily Live quota, incorporating whether an active Failover Credit balance is currently shielding requests from HTTP 429.


5. Client Integration Pattern (Telemetry & Backoff)

Production services integrating GoGoDuk should inspect X-Quota-Source and distinguish per-minute throttling from daily exhaustion in 429 error handling:

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; serving from failover credits. Remaining=${creditsRemaining}`,
  );
}
 
if (res.status === 429) {
  const err = await res.json().catch(() => ({}));
  if (err?.code === "RATE_LIMIT_MINUTE") {
    // Apply short exponential backoff (60 req/min burst ceiling hit)
  } else if (err?.code === "RATE_LIMIT_DAY") {
    // Both daily Live quota and Failover Credit Wallet exhausted (resets at 00:00 UTC)
  }
}

Architectural Takeaway

Separating environment-isolated daily pools (SANDBOX vs LIVE) from a non-expiring Failover Credit Wallet gives developers predictable baseline ceilings while keeping production traffic resilient against unexpected spikes — with full per-response transparency through standard HTTP headers.

Want to use GoGoDuk?

Start on Free (100 Live + 100 Sandbox req/day), expand daily quota via Starter/Pro infrastructure support, or enable a non-expiring Failover Credit Wallet.

Sign up →