Distributed API Rate Limiting & Idempotency at Scale: Redis Keyspace Architecture & Lock Patterns

Distributed API rate limiting and idempotency at scale rely on two key guarantees: protecting downstream services from traffic spikes and ensuring duplicate client payloads execute exactly once. Redis keyspace architecture offers a scalable solution for implementing these guarantees.

Distributed rate limiting can be achieved through the Sliding Window Log Pattern using Redis sorted sets. This approach tracks request timestamps in a sliding window range, prunes expired tokens atomically, and evaluates current volume in O(log N + M) time complexity. The Lua script provided demonstrates how to implement this pattern in Redis.

Idempotency is crucial for preventing duplicate side effects caused by network timeouts, client retries, or webhook delivery loops. By intercepting requests containing an Idempotency-Key HTTP header, a state machine manages the request lifecycle. The server enters an IN_PROGRESS state with a short TTL lock, followed by a COMPLETED state where the response is cached in Redis with a long TTL.

If an unhandled error occurs, the lock is immediately released to allow retries. Implementing this pattern as a middleware interceptor in Fastify/Express ensures efficient processing of idempotent requests.