API Rate Limit Info

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/api-rate-limit-info/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Explicit rate-limit headers (X-RateLimit-*) on every response and a status endpoint showing current quota, reset time, and request cost. Developers can predict quota exhaustion before hitting 429.

The problem

Developers hit rate limits and don’t know why; they can’t predict API quotas. A bulk import stalls at 80% with ‘rate limited’ and they have no idea when to retry or if they’re hitting the right limit.

What it does

• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers on every response
• Request cost calculation (read = 1 point, write = 10 points, bulk = 100 points)
• GET /api/rate-limit/status endpoint showing quota, remaining, and reset time
• Per-API-key quota tracking (not per-IP; two keys from same IP have separate quotas)
• Rate limit headers in error responses (429 includes remaining and reset time)
• Reset timestamp in ISO 8601 format (human-readable and machine-parseable)
• Public cost model documented in OpenAPI schema (which endpoints cost how much)
• Admin rate limit usage chart (per key, last 24 hours)
• Cost model viewer (categorize endpoints by cost tier)
• Rate limit event log (when each key hit 0 remaining)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Tiered rate limits by subscription plan (reason: belongs to paid commerce suite; core is single-tier for all keys)
• Rate limit bypasses for ‘premium’ keys (reason: no licensing model; all keys have same limits)
• Request queuing (reason: belongs to paid integration addon; core returns 429, developers implement retry logic)
• Cost negotiation per customer (reason: not a billing decision; core owns the cost model for all)
• Rate limit analytics dashboard (reason: paid analytics addon; core only surfaces current quota)

Data model

none

API

• GET /api/rate-limit/status

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Rate limit usage chart per API key (last 24 hours, hourly buckets). Cost model viewer (what costs 1 point, 10, etc.). Manual quota adjustment button for testing. Rate limit event log (which keys hit limit, when).

The seam — why this is core

Core owns rate-limit calculation and header generation on every response. Rate limiting is infrastructure; merchants don’t pay for different limits based on tier.

Core owns the interface + honest rate-limit reporter; API transparency is infrastructure, not a credential or support commitment.

Dependencies

• Existing API key system
• Request middleware
• Response middleware (to inject headers)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Every API response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers
• A bulk order import endpoint returns X-RateLimit-Cost: 100 (not 1)
• When a developer reaches 0 remaining, the next request returns 429 with reset time in header
• Reset time in 429 response matches X-RateLimit-Reset from prior successful response (no drift)
• Rate limit tracking is per API key, not per IP (two keys from 1.2.3.4 have separate quotas)
• GET /api/rate-limit/status returns current remaining and reset time in ISO 8601
• Rate limits are reset exactly at the stated reset time (not 60 seconds early or late; tested with time-shift)

Risks

If costs are wrong, developers waste quota on cheap operations or can’t do expensive operations they expected to work. If reset time is calculated incorrectly, developers retry at the wrong time and fail again. If headers are added after response body is sent, developers see stale info. If per-key tracking is broken, one noisy integration affects all developers sharing the system.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.