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-Afterso 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.