API Rate Limiting

Rate limiting is implemented through several algorithms, each with different tradeoffs. Fixed Window: count requests per defined window (e.g., 1,000 requests per hour). Simple but vulnerable to bursting at window boundaries. Sliding Window: a rolling time window (e.g., 1,000 requests in any 60-minute period) eliminates boundary bursting. Token Bucket: customers accumulate "tokens" at a steady rate up to a maximum, and each request costs one token. Allows bursty traffic up to the bucket size while enforcing sustained average limits — closest to real-world usage patterns. Leaky Bucket: processes requests at a fixed rate, queuing excess requests — smooths traffic completely but introduces latency during bursts. Most SaaS platforms use Token Bucket or Sliding Window because they balance flexibility for legitimate bursty usage patterns with protection against sustained abuse or runaway code.

Rate limit errors (HTTP 429 "Too Many Requests") are frequently misdiagnosed as bugs rather than expected API behavior. Support must: first verify the customer is actually exceeding their plan's rate limit (check API usage data in the admin dashboard); educate on the 429 response and its retry-after header (the API response includes the time until the next request will be accepted — correct clients should implement exponential backoff when they receive 429s rather than immediately retrying); investigate whether the customer's implementation is correctly handling rate limits (many integration bugs come from infinite-retry loops that make the rate limit problem worse); determine if the customer has a legitimate need for a higher rate limit (an enterprise customer whose use case requires higher throughput may warrant a custom limit or plan upgrade); and document rate limit questions systematically to inform whether plan-level limits are appropriate or need adjustment.

Rate limits are a product design and commercial decision, not just a technical constraint. Product Ops should ensure rate limits are: documented explicitly in the public API reference (including per-endpoint limits, not just global limits); differentiated by pricing tier (higher-plan customers receive higher limits — this creates a concrete, tangible benefit to upgrades); surfaced in real time through a usage dashboard in the product (customers should be able to see their current consumption against their limit, with alerts before they hit the ceiling); and accompanied by a clear upgrade path (a banner or email triggered when a customer reaches 80% of their rate limit directs them to upgrade rather than simply failing with 429s). Rate limit-driven upgrades are a measurable expansion revenue driver that Product Ops tracks alongside other expansion triggers.