如何通过 limit_req_status 自定义限流触发时的返回状态码-Nginx-PHP中文网

Nginx 的 limit_req_status 指令可自定义限流返回状态码（默认503），需与limit_req同级配置，支持400–599范围，常设为429，并可通过error_page配合返回JSON提示。

如何通过 limit_req_status 自定义限流触发时的返回状态码

Nginx 的 limit_req 模块默认在触发限流时返回 503 Service Temporarily Unavailable，但可以通过 limit_req_status 指令自定义该状态码，让限流响应更符合业务语义（例如返回 429 Too Many Requests）。

配置 limit_req_status 的基本用法

该指令需放在 http、server 或 location 块中，且必须与 limit_req 配合使用。它只影响由限流规则直接拒绝的请求，不影响其他错误（如后端超时、上游不可达等）。

语法： limit_req_status ;，例如 limit_req_status 429;
支持的状态码范围是 400–599，常见可选值包括 429、403、444（Nginx 特有，表示关闭连接且不发响应体）
若未显式配置，始终默认为 503

结合 limit_req 使用的完整示例

以下配置对 /api/ 接口按 IP 限流（10r/s），并返回 429 状态码：

http {
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=api_limit burst=20 nodelay;
            limit_req_status 429;

            proxy_pass http://backend;
        }
    }
}

注意：limit_req_status 必须写在 limit_req 所在的同一作用域内，否则不生效；如果多个 limit_req 规则共存，该指令对当前作用域下所有限流生效。

NaturalReader

NaturalReader是一款AI音频处理工具，AI文本转语音工具。

下载

配合自定义响应体提升用户体验

Nginx 本身不提供限流响应体定制功能，但可通过 error_page 拦截自定义状态码，并返回 JSON 提示：

先设置 limit_req_status 429;
再用 error_page 429 = @rate_limited; 重定向到内部 location
在 @rate_limited 中返回标准 JSON 响应，例如：{"error":"too_many_requests","retry_after":1}

这样既保持 HTTP 语义清晰（429 表示频次超限），又能让客户端获得结构化提示。