Quota

Definition

A quota is a hard limit on the total amount of resources you can consume from an API within a defined time period - typically measured in requests per day, storage capacity, compute hours, or data transfer. Unlike rate limiting (which controls how fast you make requests), quotas control how much you can use overall. Think of rate limiting as speed limits on a highway, while quotas are the total miles you’re allowed to drive this month.

Quotas serve multiple business and technical purposes. They prevent resource exhaustion (one user can’t consume all available capacity), enable tiered pricing models (free users get 1,000 requests/day, premium users get 1 million), and make costs predictable for both providers and consumers. When you hit your quota, you’re done until the next reset period - there’s no queuing or throttling, just a hard stop.

The key distinction: rate limiting protects real-time system stability (preventing server crashes), while quotas protect long-term resource allocation and enable business models. You might have a rate limit of 100 requests per second but a quota of 1 million requests per month. You can burst fast (within rate limits) but you can’t exceed your total allocation.

Example

Google Maps API: Free tier includes 28,000 map loads per month. Once you hit 28,000, all subsequent requests return an error until next month. This quota prevents unexpected bills and ensures Google’s infrastructure is fairly distributed across customers.

AWS Lambda: You might have a quota of 1,000 concurrent executions and 75 GB of total code storage. Trying to deploy a 76th GB fails immediately. The quota ensures AWS can capacity plan and prevents runaway costs.

OpenAI API: GPT-4 might have a quota of $100 credit per month on a free account. Each request consumes tokens (costs money), and when you hit $100, requests fail until you upgrade or next month arrives. This protects both you (from surprise bills) and OpenAI (from abuse).

GitHub API: Authenticated users get 5,000 requests per hour. After 5,000, you receive 403 Forbidden with a message indicating when your quota resets. This is both a rate limit (hourly window) and a quota (hard cap on total requests).

Stripe API: Free plans might have a quota of 100 test mode transactions per day. Once you hit 100, you can’t create more test charges until tomorrow. This prevents abuse of free testing infrastructure.

Cloud Storage: Dropbox gives you 2 GB of storage quota for free. You can upload files as fast as you want (rate limit), but once you hit 2 GB, uploads fail until you delete files or upgrade.

Analogy

The Cell Phone Data Plan: You have 10 GB of data per month. You can use it as fast as your LTE connection allows (rate limiting), but once you hit 10 GB, you’re either throttled to 2G speeds or cut off entirely (quota exceeded). Next month, your quota resets to 10 GB.

The Gym Membership: A budget gym might limit you to 50 visits per month. You can go every day (rate: 1 visit/day), but after 50 visits, you’re locked out until next month. The quota protects the gym from overcrowding while offering affordable pricing.

The All-You-Can-Eat Buffet with a Twist: Imagine a buffet that lets you visit 5 times per hour (rate limit) but has a total quota of 20 plates per day. You can load up fast within rate limits, but after 20 plates, you’re done regardless of time remaining.

The Paid Time Off (PTO) Balance: You accrue 15 vacation days per year (your quota). You can take them whenever you want within company policy (rate limits on consecutive days off), but once you’ve used all 15, you can’t take more until next year when your quota resets.

Code Example

// Server-side quota tracking with Redis
import Redis from 'ioredis';
const redis = new Redis();

async function checkQuota(userId, quotaLimit, windowSeconds) {
  const key = `quota:${userId}:${Math.floor(Date.now() / 1000 / windowSeconds)}`;
  const currentUsage = await redis.get(key);

  if (currentUsage && parseInt(currentUsage) >= quotaLimit) {
    // Quota exceeded
    const ttl = await redis.ttl(key);
    return {
      allowed: false,
      remaining: 0,
      resetIn: ttl,
      message: `Quota exceeded. Resets in ${ttl} seconds.`
    };
  }

  // Increment usage
  const newUsage = await redis.incr(key);

  // Set expiration on first use
  if (newUsage === 1) {
    await redis.expire(key, windowSeconds);
  }

  return {
    allowed: true,
    remaining: quotaLimit - newUsage,
    resetIn: await redis.ttl(key),
    usage: newUsage
  };
}

// Express.js middleware
async function quotaMiddleware(req, res, next) {
  const userId = req.user?.id || req.ip;
  const userTier = req.user?.tier || 'free';

  // Different quotas per tier
  const quotas = {
    free: { limit: 1000, window: 86400 },    // 1,000/day
    pro: { limit: 100000, window: 86400 },   // 100,000/day
    enterprise: { limit: 10000000, window: 86400 } // 10M/day
  };

  const { limit, window } = quotas[userTier];
  const result = await checkQuota(userId, limit, window);

  // Set quota headers
  res.setHeader('X-Quota-Limit', limit);
  res.setHeader('X-Quota-Remaining', result.remaining);
  res.setHeader('X-Quota-Reset', Date.now() + (result.resetIn * 1000));

  if (!result.allowed) {
    return res.status(429).json({
      error: 'quota_exceeded',
      message: result.message,
      limit: limit,
      resetAt: new Date(Date.now() + result.resetIn * 1000).toISOString()
    });
  }

  next();
}

// Usage
app.use(quotaMiddleware);

app.get('/api/data', async (req, res) => {
  // This endpoint is protected by quota
  res.json({ data: 'Your data' });
});

Diagram

graph TB
    subgraph User["User / API Client"]
        U[Makes API Requests]
    end

    subgraph Gateway"[API Gateway / Middleware"]
        Q[Quota Checker]
        T[Tier Detection]
        R[Redis / DB]
    end

    subgraph Quotas["Quota Tiers"]
        F["Free Tier
1,000 req/day"]
        P["Pro Tier
100,000 req/day"]
        E["Enterprise
10,000,000 req/day"]
    end

    subgraph Backend["Backend API"]
        B[Process Request]
        D[(Database)]
    end

    U -->|Request + API Key| Q
    Q --> T
    T -.Check Tier.-> F
    T -.Check Tier.-> P
    T -.Check Tier.-> E
    Q -->|Check Usage| R
    R -->|Current: 850/1000| Q

    Q -->|Under Quota| B
    Q -->|Exceeded Quota| X[429 Quota Exceeded
X-Quota-Reset: timestamp]

    B --> D
    B -->|Success + Headers
X-Quota-Remaining: 149| U

    style Q fill:#ffe6e6
    style R fill:#e6f3ff
    style X fill:#ffcccc
    style F fill:#f0f0f0
    style P fill:#e6ffe6
    style E fill:#e6e6ff

Security Notes

Best Practices

1. Tiered Quotas: Offer multiple subscription levels with different quotas (free, pro, enterprise). This enables business growth while protecting free tier resources.

2. Clear Communication: Show users their current usage and remaining quota in API responses and dashboards. Nobody likes surprise quota errors.

3. Graceful Degradation: When approaching quota limits, warn users in advance (e.g., “You’ve used 90% of your quota”) rather than abruptly blocking at 100%.

4. Quota Headers: Include quota information in every API response:

   • X-Quota-Limit: Total quota
   • X-Quota-Remaining: Remaining quota
   • X-Quota-Reset: When quota resets (Unix timestamp)

5. Sliding Windows: Use sliding window quotas (last 30 days) instead of fixed calendar months to prevent boundary abuse (users maxing out on day 30, then again on day 1).

6. Granular Quotas: Different operations have different costs. Apply separate quotas for expensive operations (AI model calls, video processing) vs. cheap ones (fetching cached data).

7. Burst Allowance: Consider allowing short bursts above quota if the average is under quota. This smooths out spiky usage patterns.

8. Quota Carryover: For paid tiers, consider allowing unused quota to roll over to the next period (up to a limit) to increase customer satisfaction.

Common Mistakes

No Quota Visibility: Users shouldn’t have to guess their quota status. Always expose current usage in API responses and provide a dashboard.

Fixed Calendar Windows: Resetting quotas at midnight on the 1st creates an exploit - users can max out on the last day of the month and again on the first day.

No Soft Limits: Blocking users at exactly 100% quota with no warning creates bad UX. Warn at 80% and 90%.

Client-Side Quota Tracking: Never rely on clients to track their own quota usage. Malicious clients will lie.

Quota Per Request Instead of Resource: Counting requests is easy but unfair. Downloading 1 KB should not count the same as processing a 5 GB video.

No Quota Persistence: Storing quota in memory means server restarts reset usage. Always use persistent storage (DB, Redis).

Identical Quotas for All Users: Free users and enterprise customers shouldn’t share the same quota. Implement tiered quotas based on subscription level.

No Upgrade Path: When legitimate users hit quotas, offer a clear path to upgrade. Otherwise, they’ll find a competitor.

Quota on Authentication: Be careful applying quotas to login/signup endpoints. Too restrictive and legitimate users can’t access your service.

Standards & RFCs

Related Terms