rate_limit_headers
The rate_limit_headers directive enables the inclusion of rate limiting headers in HTTP responses.
Description
The rate_limit_headers directive, when set to 'on', allows NGINX to send specific HTTP headers related to rate limiting in responses to clients. These headers inform clients about the rate limit parameters that are currently in effect, including the maximum number of allowed requests, the number of remaining requests within the current time period, the time until the rate limit resets, and any recommended wait time before making additional requests if limits are reached. The headers are named 'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reset', and 'Retry-After', and they provide transparent communication regarding the rate limiting status for every request processed by the server.
Using this directive is particularly useful in API scenarios, where clients need clear feedback on their usage and limits imposed by the service. When a client hits their rate limit, the server can respond with a 429 Too Many Requests status code along with the appropriate headers, allowing clients to adapt their request strategies accordingly. The directive is flexible, being applicable at the http, server, or location contexts, enabling fine-tuned control over when headers should be included depending on the application's rate limiting requirements.
Config Example
location /quota {
rate_limit $limit_key requests=15 period=1m burst=20;
rate_limit_quantity 0;
rate_limit_pass redis;
rate_limit_headers on;
}Ensure the rate limiting logic is correctly configured to avoid sending misleading headers after a user exceeds their limit.
The presence of headers may encourage clients to misuse rate limiting limits by hammering the server with requests just below the limit threshold.