What Headers to Use for Rate Limiting in REST APIs

Use the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers to communicate rate limiting information in REST APIs. These headers tell clients their total allowed requests, remaining requests, and when the limit resets.

Syntax

Rate limiting headers typically include:

• RateLimit-Limit: The maximum number of requests allowed in the current time window.
• RateLimit-Remaining: How many requests the client can still make before hitting the limit.
• RateLimit-Reset: The time (usually in seconds or a timestamp) when the rate limit will reset.

These headers help clients understand their usage and avoid being blocked.

http

RateLimit-Limit: 1000
RateLimit-Remaining: 750
RateLimit-Reset: 3600

Example

This example shows a simple HTTP response with rate limiting headers indicating a limit of 1000 requests, 750 remaining, and reset in 3600 seconds (1 hour).

http

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 1000
RateLimit-Remaining: 750
RateLimit-Reset: 3600

{"message": "Request successful"}

Output

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 1000
RateLimit-Remaining: 750
RateLimit-Reset: 3600

{"message": "Request successful"}

Common Pitfalls

Common mistakes when using rate limiting headers include:

• Not updating RateLimit-Remaining correctly after each request.
• Using inconsistent time units in RateLimit-Reset (seconds vs timestamps).
• Omitting these headers entirely, leaving clients unaware of limits.
• Using non-standard or custom header names that clients do not recognize.

Always follow standard header names and keep values accurate to help clients manage their request rates.

http

Wrong:
RateLimit-Remaining: 1000  # Does not decrease
RateLimit-Reset: 1 hour    # Ambiguous format

Right:
RateLimit-Remaining: 999
RateLimit-Reset: 3600  # Seconds until reset

Quick Reference

Header	Purpose	Example Value
RateLimit-Limit	Maximum requests allowed in time window	1000
RateLimit-Remaining	Requests left before limit is reached	750
RateLimit-Reset	Seconds until limit resets	3600

Key Takeaways

Use standard headers RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset to inform clients about rate limits.

Keep RateLimit-Remaining updated accurately after each request to avoid client confusion.

Express RateLimit-Reset in seconds or as a clear timestamp to indicate when limits reset.

Avoid custom or inconsistent header names to ensure client compatibility.

Providing these headers helps clients manage their request rates and prevents unexpected blocking.