Course contentsShow
← System Design
Lesson 960 of 1,91925. Rate Limiting and ThrottlingFree lesson

Rate Limit Response Codes

Learn HTTP 429 Too Many Requests, retry headers (Retry-After, X-RateLimit-*), and client communication.

Rate Limit Response Codes

What you'll learn: How to properly communicate rate limit violations to clients using standard HTTP status codes and headers.


When your system enforces a rate limit, it needs to tell the client why their request was rejected and when they can try again. Simply blocking requests without explanation creates a terrible developer experience and debugging nightmare.

HTTP 429: Too Many Requests

The standard response when a client exceeds their rate limit is HTTP 429 Too Many Requests. This clearly signals "you're going too fast" rather than a generic error. Think of it like a polite bouncer saying "Hey, you're at capacity, come back later" versus just slamming the door.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"error": "Rate limit exceeded"}

Essential Rate Limit Headers

Clients need actionable information, provided through standard headers:

Retry-After

Tells the client when they can retry (in seconds or as an HTTP date):

Retry-After: 60

X-RateLimit-* Headers

Common convention (though not standardized) for transparency:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

These tell the client their quota, how many requests remain, and when their limit resets. Include these on all responses (successful or not) so clients can implement smart backoff strategies.

Client Communication Best Practices

  • Always return 429, not 503 or 500
  • Include Retry-After so clients know exactly when to retry
  • Provide rate limit headers proactively on successful requests too
  • Document your limits clearly in API documentation
  • Be consistent across all endpoints

Key Takeaway: Use HTTP 429 with Retry-After and X-RateLimit-* headers to clearly communicate rate limit violations, enabling clients to handle throttling gracefully and adjust their behavior intelligently.