limit_req_status
The `limit_req_status` directive specifies the HTTP status code returned to clients when a request is rejected due to rate limiting.
Description
The limit_req_status directive is part of the NGINX HTTP Core module and is utilized in conjunction with rate limiting features provided by the limit_req directive. When a client exceeds the allowed request rate, the specified HTTP status code is returned in response to their requests that are rejected by the limit request handling mechanism. This allows for a custom message, such as a 503 Service Unavailable, to inform the client of the throttling rather than simply failing to process their requests.
This directive accepts a single argument: the desired HTTP status code that should be sent in the response when the request limits are exceeded. Users can specify any valid HTTP status code, allowing for flexibility based on their application's requirements. Commonly used status codes include 503 for service unavailability or 429 for too many requests. It's important to note that this directive affects only those requests that are not processed due to limit restrictions and does not impact successful requests that are within the limits.
As a configuration directive, it can be defined at the http, server, or location context levels, providing the flexibility to apply different status codes based on varying scopes of the application. Developers should ensure that the specified status code aligns with their application's error handling logic and user expectations when rate limiting is enforced.
Config Example
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
server {
location / {
limit_req zone=one;
limit_req_status 503;
}
}Using a status code that is not valid may lead to unexpected behavior or errors in the client applications.
If limit_req is not properly set up, clients may not receive the configured status, as the directive is ineffective without active rate limiting.