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.

Sign up — free See India coverage →