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:
- 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.
- 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 Requestserrors 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):
| Configuration | Cycle | Live / day | Sandbox / day | Per-minute burst | Max API keys |
|---|---|---|---|---|---|
Free (0đ) | Forever | 100 req | 100 req | 60 req/min | 10 keys |
Starter (129,000 VND) | 30 days | 350 req (~10,500/mo) | 200 req | 60 req/min | 10 keys |
Pro (249,000 VND) | 30 days | 750 req (~22,500/mo) | 300 req | 60 req/min | 10 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
SANDBOXkey consume strictly from the daily Sandbox pool (100/200/300req/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,000Credits - C12K (Growth Pack) —
199,000 VND:12,000Credits (includes+2,000/+20%bonus Credits) - C35K (Scale Pack) —
499,000 VND:35,000Credits (includes+10,000/+40%bonus Credits)
- C5K (Starter Pack) —
3. Waterfall Evaluation Order & Abuse Safeguards
Every API call entering the GoGoDuk Gateway passes through a deterministic evaluation pipeline:
Guardrails against unintended Credit drain
- 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, the60 req/minceiling drops excess calls immediately before reaching the Credit ledger, protecting your backup balance. - Automatic
+1 Creditrefund on5xxerrors (X-Quota-Refunded: 1): If a request consumes a Failover Credit (X-Quota-Source: credit) and the upstream handler fails with a5xxstatus code, the gateway automatically credits+1back within the request lifecycle and flagsX-Quota-Refunded: 1. - Non-deductible system traffic:
GET /v1/usagepolling 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:
Header semantics:
X-Quota-Source: Indicates which bucket served the request —daily(daily quota tier) orcredit(Failover Credit Wallet).X-RateLimit-Remaining-Day: Remaining requests in today's daily quota pool (until00:00 UTC). Seeing0alongsideX-Quota-Source: creditconfirms failover is active.X-Credits-Remaining: Updated Failover Credit balance after this request.X-Quota-Refunded: Present with value1when a5xxfailure triggered an automatic+1 Creditrefund.
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:
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 →