Rate Limit Errors — 429 Too Many Requests

In this tutorial, you will learn about Rate Limit Errors. We cover key concepts, practical examples, and best practices to help you master this topic.

Rate limit errors (429) indicate the client exceeded the allowed request rate, returning retry timing information via headers and a standard error body.

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1624896000
Retry-After: 60

Implementation

app.use("/api/", rateLimit({
  windowMs: 60 * 1000,
  max: 100,
  handler: (req, res) => {
    res.status(429).json({
      status: 429,
      error: "rate_limited",
      message: "Too many requests. Please wait before retrying.",
      retryAfter: Math.ceil(req.rateLimit.resetTime / 1000 - Date.now() / 1000)
    });
  }
}));

Common Mistakes

1. No Retry-After header — Clients do not know when to retry.
2. No rate limit headers on success — Clients need remaining count to pace requests.
3. Throttling without notification — Silently dropping requests.

Practice Questions

1. What headers should accompany 429 responses?
2. What is the Retry-After header format?
3. Why include rate limit headers on successful responses?

What's Next

In the next lesson, you will learn error middleware patterns.