June 20, 2026 · 6 min read · Industry
Rate-limiting a B2B travel API: per-minute vs per-month, and why both.
Single-scale rate limits are a residual habit from consumer APIs. B2B workloads need two: a per-minute cap to shield production from runaway retries, and a per-month cap to make pricing tiers predictable. Most travel APIs ship one or the other. We ship both.
Why per-minute matters
A customer's job queue gets stuck. Their retry loop fires every 50ms against /v1/cities for the same query. With a monthly-only quota, they burn through 50,000 calls in fifteen minutes, hit the wall, and your support inbox lights up at 3am. Worse, the burst saturates a shard and degrades latency for everyone else on the same server.
Per-minute caps are a circuit breaker. If a client exceeds its plan's per-minute limit (120 a minute on Starter), it gets a 429; the retry loop stops mattering because every retry returns immediately. The customer's runbook fires before the monthly quota is touched.
Why per-month matters
Per-minute alone makes pricing unpredictable. A Starter account at 120 requests a minute could in theory pull about 5.2M calls a month if its workload were steady. That isn't what it pays for. The monthly cap is the contract: 250,000 on Starter, 1,500,000 on Growth, 5,000,000 on Scale; the free trial is 5,000 calls, once. Predictable pricing for the customer, predictable cost for us.
The headers we return
Corrected 13 November 2026: this section used to show
X-RateLimit-*-Month headers and a 429 body with a
scope field. Our API does not send them. What follows is
what our gateway code sends today.
A successful data response made with an API key carries both scales.
The per-minute window uses the common X-RateLimit-* names;
the allowance uses our own X-Tmai-Quota-* names. A request
without a key gets a 401 and none of these headers.
HTTP/1.1 200 OK
X-RateLimit-Limit: <your plan's per-minute limit>
X-RateLimit-Remaining: <that limit minus one>
X-RateLimit-Reset: 60
X-Tmai-Quota-Limit: <your allowance>
X-Tmai-Quota-Remaining: <what is left of it>
X-Tmai-Quota-Period: monthly
X-Tmai-Quota-Reset-At: <first day of next month, 00:00 UTC>
On a 200, X-RateLimit-Remaining is approximate: it is always
the limit minus one. On the free trial, X-Tmai-Quota-Period
is one_time and there is no X-Tmai-Quota-Reset-At.
The 429 answers
Over the per-minute limit:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 60
{ "detail": "Rate limit exceeded (<n>/<limit> requests in last 60s)." }
A paid plan over its monthly allowance:
HTTP/1.1 429 Too Many Requests
Retry-After: <seconds until the first day of next month>
X-Tmai-Quota-Limit: <your allowance>
X-Tmai-Quota-Remaining: 0
X-Tmai-Quota-Reset-At: <first day of next month>
{ "error": "quota_exceeded", "message": "...", "used": ..., "quota": ...,
"reset_at": "...", "upgrade_url": "https://travelminds.ai/pricing",
"recommended_plan": "...", "projected_monthly_usage": ... }
The free trial used up (it never resets, so there is no Retry-After):
HTTP/1.1 429 Too Many Requests
X-Tmai-Quota-Limit: 5000
X-Tmai-Quota-Remaining: 0
X-Tmai-Trial: exhausted
{ "error": "trial_exhausted", "message": "...", "used": ..., "quota": ...,
"reset_at": null, "upgrade_url": "https://travelminds.ai/pricing",
"recommended_plan": "starter" }
The body tells the cases apart. A per-minute 429 has only
detail; an allowance 429 has error set to
quota_exceeded or trial_exhausted. The first
backs off; the second escalates to a human or upgrades the plan.
Backoff that respects both scales
Naive exponential backoff starts at 1 second and doubles. Against an exhausted allowance this is wrong: the client retries for an hour before it sees that nothing is left. Honour Retry-After on a per-minute 429, and stop on an allowance 429:
async function call(url) {
const r = await fetch(url, { headers: { Authorization: "Bearer " + API_KEY } });
if (r.status !== 429) return r;
const body = await r.json();
if (body.error === "quota_exceeded" || body.error === "trial_exhausted") {
throw new QuotaExhausted(body.message);
}
const delay = parseInt(r.headers.get("Retry-After") || "60", 10) * 1000;
await sleep(delay);
return call(url);
}
What happens at the boundaries
Per-minute window: sliding, computed on a 60-second tail. Not a fixed minute boundary. A Growth client (600 a minute) that fires 600 calls at 12:00:30 and another 600 at 12:01:30 is fine. A client that fires 1,200 calls in the same second is not.
Per-month window (paid plans; the free trial never resets): calendar month in UTC. Resets at 00:00 UTC on the 1st of each month. Not 30 days from signup, not the customer's timezone: UTC. The X-Tmai-Quota-Reset-At header gives that time for clients that want to render their own usage chart.
Industry context
Stripe ships per-minute and per-second on writes, no monthly quota (because they bill per transaction, not per call). Twilio ships per-second on send, monthly billing per message. AWS ships per-second burst with token-bucket credit accumulation. Google Maps Platform ships QPS plus monthly billing thresholds.
For a travel data API, the two scales we care about are minute and month. Per-second is too tight for typical travel workloads (most queries are not user-blocking). Per-day is too coarse to be useful against runaway retries. Minute and month is the sweet spot.