engineering

API Quotas vs Rate Limits: The Distinction That Saves Customer Support Tickets

Most APIs conflate quotas and rate limits, returning the same 429 status for both. The distinction matters because the right response from the customer is different in each case, and conflating them produces support tickets about charges that customers cannot diagnose without reading source cod

Anethoth

— 4 min read

The conflation of quotas and rate limits is one of the more common API design mistakes. A customer hits an error, sees a 429 status code, and has no way to tell whether they need to back off for a few seconds, upgrade their plan, or wait until next month. The result is support tickets, customer frustration, and a class of failure that the API team could have prevented with three lines of additional response data.

We learned this distinction the hard way across DocuMint, CronPing, FlagBit, and WebhookVault. The customers who hit these limits are the customers who are using the product most, which means conflating the two errors loses you the customers you most want to keep.

The two distinct mechanisms

A rate limit is a short-window operational concern. It exists to protect the API from abuse, runaway clients, and load spikes that exceed serving capacity. The window is seconds or minutes. The right response is to back off and retry; the customer has done nothing wrong. Rate limits typically reset on a sliding window of a few minutes.

A quota is a contractual concern. It enforces the limits that the customer signed up for. The window is days or months. The right response is to upgrade the plan or wait for the quota to refresh; the customer has used what they paid for. Quotas typically reset at the start of the billing period.

The two have different operational consequences, different customer-side actions, and should have different error responses. Returning a 429 for both forces the customer to read documentation or reverse-engineer the API to figure out which mode they have hit. This is the kind of friction that drives customers to competitors who handle the case more gracefully.

The minimum viable response distinction

The smallest change that makes the two cases distinguishable is using different status codes:

  • 429 Too Many Requests for rate limit violations
  • 402 Payment Required or 403 Forbidden with a specific error code for quota violations

The status code alone is not enough. The response body should make the distinction unambiguous:

// Rate limit response
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715000000

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 30 seconds.",
    "type": "rate_limit",
    "retry_after_seconds": 30
  }
}

// Quota response
HTTP/1.1 402 Payment Required
X-Quota-Limit: 10000
X-Quota-Used: 10000
X-Quota-Reset: 1717689600

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota of 10000 invoices reached on your Starter plan. Upgrade at https://documint.anethoth.com/billing or wait until 2026-06-01.",
    "type": "quota",
    "upgrade_url": "https://documint.anethoth.com/billing",
    "resets_at": "2026-06-01T00:00:00Z"
  }
}

The customer reading the quota response knows immediately what action to take. The customer reading the rate limit response knows to wait. Neither requires reading documentation to diagnose.

The headers tell the story without parsing JSON

The X-RateLimit and X-Quota headers serve a specific purpose: they let well-behaved clients monitor their position without parsing error bodies. A customer building a long-running integration can read these headers on every successful response, not just on errors, and back off preemptively when they see the remaining count get low.

The Retry-After header for rate limits is standard and well-understood. For quotas, a Retry-After header is misleading because the wait is days or weeks; an explicit reset timestamp is more honest.

The implementation: two separate counters

The two limits need separate counters in the implementation. Rate limits typically live in a fast in-memory store like Redis with second-resolution keys. Quotas live in the main database with append-only usage records that the billing system can audit.

Combining them into a single counter is appealing because it is simpler, but the appeal is illusory. The two have different reset windows, different audit requirements, and different operational characteristics. The billing system needs the quota count to be exactly right for the month, with auditable history per request. The rate limit just needs to be approximately right for the last minute.

Our implementation across the four products uses Redis token buckets for rate limits with one-second resolution and PostgreSQL append-only tables for quota usage with per-request rows. Quota checks happen at the start of each request handler; rate limit checks happen in middleware. The two never share data structures.

The middle case: soft quotas

A useful middle ground is the soft quota, which exceeds the contractual limit by some margin (say, 10 percent) and bills for the overage. This is the right pattern for any product where running out mid-month is operationally painful for the customer. Stripe uses this pattern for many of its API products; AWS uses it for everything.

The implementation is the same as a hard quota plus a billing record for the overage. The customer-facing behavior is much friendlier: the API keeps working, the customer gets an email about the overage, and the bill explains the charge clearly.

The wrong answer: silent throttling

One pattern to avoid is silent throttling, where requests over the limit are delayed rather than rejected. This is appealing because it does not produce errors, but it has two failure modes that the customer cannot diagnose: latency spikes that look like infrastructure problems, and request queues that exhaust client-side timeouts. The customer would much rather see an explicit 429 with a Retry-After header than experience their API client mysteriously becoming slow.

The five customer-side patterns to support

Once the distinction is clear in the API responses, customers can adopt the standard patterns:

  1. Exponential backoff on 429s: wait the suggested time, retry, double the wait on subsequent failures.
  2. Token bucket pacing: read the X-RateLimit headers and pace request volume to stay under the limit.
  3. Proactive upgrade: monitor X-Quota-Used as a percentage of X-Quota-Limit and prompt for upgrade when it crosses 80 percent.
  4. Graceful degradation: when the quota is exhausted, fall back to cached or partial data rather than failing the user-facing operation.
  5. Cost monitoring: log every quota-counted request with its cost weight, surface monthly aggregates to the customer's own monitoring.

None of these patterns are possible if the API conflates the two errors. The customer cannot back off correctly on a quota violation (it will not help) and cannot upgrade correctly on a rate limit violation (it would not fix the problem).

The deeper observation

Conflating two distinct concerns into one error code is a recurring pattern in API design. It is appealing because it feels parsimonious: fewer codes, fewer cases, less documentation. The cost is paid every time a customer hits the conflation and has to figure out which case they are in.

The right discipline is to distinguish errors by what the customer should do next, not by what went wrong on the server side. The customer who hit a rate limit and the customer who hit a quota have different next actions, and the API response should make those actions obvious without requiring inference or documentation lookup.

Read more