How to Design Rate Limit Response for REST APIs

To design a rate limit response, use the HTTP status code 429 Too Many Requests and include headers like Retry-After to tell clients when to try again. This informs clients politely that they have exceeded allowed requests and helps them handle limits gracefully.

Syntax

A typical rate limit response uses the HTTP status code 429 Too Many Requests. It should include headers such as Retry-After to specify how many seconds the client should wait before retrying. Optionally, custom headers like X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset provide more details about the limit.

• 429 Too Many Requests: Standard status code indicating rate limit exceeded.
• Retry-After: Time in seconds or HTTP date when the client can retry.
• X-RateLimit-Limit: Maximum allowed requests in the time window.
• X-RateLimit-Remaining: Remaining requests in the current window.
• X-RateLimit-Reset: Time when the rate limit resets (usually a timestamp).

http

HTTP/1.1 429 Too Many Requests
Retry-After: 120
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1618886400
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "message": "You have sent too many requests. Please wait before retrying."
}

Example

This example shows a simple REST API response when a client exceeds the rate limit. The server responds with status 429, includes a Retry-After header indicating 60 seconds wait time, and a JSON body explaining the error.

http

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

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

Output

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

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

Common Pitfalls

Common mistakes when designing rate limit responses include:

• Not using the 429 status code, which confuses clients about the error.
• Omitting the Retry-After header, leaving clients unsure when to retry.
• Not providing clear error messages in the response body.
• Failing to include rate limit headers that help clients monitor usage.

Always use standard codes and headers to ensure clients can handle limits properly.

http

Wrong way:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Rate limit exceeded"
}

Right way:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": "Too Many Requests",
  "message": "Please wait 30 seconds before retrying."
}

Quick Reference

Header	Purpose	Example
429 Too Many Requests	HTTP status code indicating rate limit exceeded	HTTP/1.1 429 Too Many Requests
Retry-After	Time client should wait before retrying (seconds or date)	Retry-After: 60
X-RateLimit-Limit	Maximum requests allowed in time window	X-RateLimit-Limit: 100
X-RateLimit-Remaining	Requests left in current window	X-RateLimit-Remaining: 0
X-RateLimit-Reset	Timestamp when limit resets	X-RateLimit-Reset: 1618886400

Key Takeaways

Use HTTP status code 429 to indicate rate limit exceeded.

Include Retry-After header to tell clients when to retry.

Provide clear error messages in the response body.

Add rate limit headers to help clients track usage.

Avoid using incorrect status codes like 403 for rate limiting.