$limit_req_status

Description

The $limit_req_status variable is used within the NGINX configuration to indicate the response status resulting from the rate limiting directives defined in the 'limit_req' module. When a request exceeds the defined rate, NGINX can return specific status codes, such as 503 (Service Unavailable) or 503 with the 'limit exceeded' message. The $limit_req_status variable captures these codes and makes them available for logging or further processing. This variable is particularly useful for creating custom error pages or handling specific responses differently based on the status. For instance, if a request is throttled due to too many requests in a short amount of time, you can use the value of $limit_req_status in your configuration to manage how to inform users about the limit being hit. Typically, it can return values like 200 for normal requests, 503 for requests that have been denied due to rate limiting, or other status codes as configured in the application. It's important to understand that the $limit_req_status variable is only populated when a valid request is processed that passes through a limit_req directive and is subject to the rate limiting behavior. If rate limiting is not in effect or if the request does not hit that directive, the variable would be unset.

Config Example

server {
    location /api {
        limit_req zone=one burst=5;
        if ($limit_req_status = 503) {
            return 429 'Too Many Requests';
        }
    }
}