Designing predictable rate limits for a country-data API

Headers first

Every response carries `X-CostMaps-Limit`, `X-CostMaps-Remaining`, and `X-CostMaps-Reset`. Clients know their state without polling a separate quota endpoint.

Daily, not monthly

We chose UTC-day windows because the use cases (compare workflows, scheduled reports) have a daily rhythm. Monthly windows produce surprise lockouts in the last week.

Bursts matter more than peak

A Pro key gets 1,000 requests/day with a 120 burst/minute. Most production workloads care more about the burst ceiling than the daily total.

Cached responses don't count

Within a 5-minute window the same query is free. This makes the dashboard usable even when the API quota is exhausted.