API Rate Limiting with Redis & Token Buckets: Full Guide

Have you ever had an API endpoint slow down because a single rogue client sent thousands of requests per second? Whether from a misconfigured script, an automated web scraper, or a malicious distributed denial-of-service attack, API abuse happens daily.

Without rate limiting, a single user can monopolize your database connections and crash your services for everyone else. Protecting your application requires enforcing fair usage boundaries.

Executive Summary

  • Protecting APIs: Unrestricted API endpoints are vulnerable to brute-force credential stuffing, scraping bots, and catastrophic denial-of-service outages.
  • The Token Bucket Algorithm: Provides the smoothest rate limiting by allowing legitimate burst traffic while enforcing strict long-term rate ceilings.
  • Redis Atomicity: Execute token bucket calculations atomically using Redis Lua scripts to eliminate race conditions across distributed microservices.
  • HTTP 429 Standards: Return standardized HTTP 429 Too Many Requests responses with Retry-After headers to instruct clients when to retry.

Table of Contents

API Rate Limiting Algorithms Compared

AlgorithmHandles Burst Traffic?Memory OverheadImplementation ComplexityBest Use Case
Fixed Window CounterNo (vulnerable to window-edge spikes)Extremely low (single integer)Very SimpleBasic hourly quotas and free-tier limits.
Sliding Window LogYes (perfect accuracy)High (stores timestamp for every call)ComplexStrict low-volume banking or auth endpoints.
Token BucketYes (smoothly accommodates bursts)Low (timestamp + counter per user)Moderate (using Redis Lua)Recommended: 90% of production public APIs.
Leaky BucketNo (enforces steady outflow rate)Low (queue-based)ModerateData ingestion pipelines and webhook dispatchers.

Why Modern APIs Must Enforce Rate Limiting

Have you ever had an API endpoint slow down because a single rogue client sent thousands of requests per second? Whether from a misconfigured script, an automated web scraper, or a malicious distributed denial-of-service attack, API abuse happens daily.

Without rate limiting, a single user can monopolize your database connections and crash your services for everyone else. Protecting your application requires enforcing fair usage boundaries.

In this guide, we will show you how to implement the token bucket rate limiting algorithm using Redis. This pattern provides atomic, distributed protection that scales effortlessly across multiple web containers.

How the Token Bucket Algorithm Works

Imagine a bucket that holds a fixed number of tokens, such as 60 tokens. Every second, new tokens are added to the bucket at a steady rate until the bucket is full.

When a client makes an API request, the server attempts to take a token from the bucket. If a token is available, the request proceeds, and the token count decreases by one.

If the bucket is empty, the server rejects the request immediately with an `HTTP 429 Too Many Requests` status. This model allows legitimate users to make short bursts of requests without being penalized, while strictly capping continuous usage.

Implementing Atomic Token Buckets with Redis and Lua

In a distributed microservice architecture, multiple application servers process requests simultaneously. Checking and decrementing token counts in separate Redis commands creates race conditions.

To ensure thread safety, wrap your token bucket logic in a Redis Lua script. Redis executes Lua scripts atomically, guaranteeing that no other command can interrupt the token calculation.

The Lua script computes how many tokens have replenished since the client’s last request, checks if enough tokens remain, decrements the balance, and sets an expiration TTL on the Redis key. All of this executes in less than a millisecond.

Returning Standard HTTP Rate Limit Headers

When rejecting or throttling clients, always communicate clearly through standard HTTP headers. This allows well-behaved API SDKs to back off automatically without erroring out.

Include headers such as `X-RateLimit-Limit: 60`, `X-RateLimit-Remaining: 14`, and `X-RateLimit-Reset: 1718000000` on every response.

When a request is blocked with status 429, include a `Retry-After: 30` header indicating how many seconds the client must wait before sending another request.

Frequently Asked Questions

Why is Redis preferred for API rate limiting?

Redis operates entirely in RAM with sub-millisecond latency. Its atomic operations and Lua script support make it ideal for tracking request counts across distributed server clusters.

What HTTP status code should rate-limited requests return?

Rate-limited requests should always return HTTP 429 Too Many Requests accompanied by a Retry-After header.

Can rate limiting be applied by user ID and IP address?

Yes. Best practice is to rate limit authenticated requests using the user ID or API key, while rate limiting unauthenticated public endpoints by client IP address.

We hope this guide helped you scale your infrastructure with confidence. Explore related tutorials from our cloud architecture cluster:

Primary Sources & References

Written by the TeckScaler Cloud & Systems Engineering Team. We design and build ultra-reliable cloud architectures, custom web platforms, and automated deployment pipelines for growing teams.