Nginx 的 limit_req_status 指令可自定义限流返回状态码（默认503），需与limit_req同级配置，支持400–599范围，常设为429，并可通过error_page配合返回JSON提示。
Nginx 的
模块默认在触发限流时返回
，但可以通过
指令自定义该
状态码
，让限流响应更符合业务语义（例如返回
）。
配置 limit_req_status 的基本用法
该指令需放在
、
或
块中，且必须与
配合使用。它只影响由限流规则直接拒绝的请求，不影响其他错误（如后端超时、上游不可达等）。
语法：
，例如
支持的状态码范围是
，常见可选值包括
、
、
（Nginx 特有，表示关闭连接且不发响应体）
若未显式配置，始终默认为
结合 limit_req 使用的完整示例
以下配置对 /api/ 接口按 IP 限流（10r/s），并返回 429 状态码：
注意：
必须写在
所在的同一作用域内，否则不生效；如果多个
规则共存，该指令对当前作用域下所有限流生效。
配合自定义响应体提升用户体验
Nginx 本身不提供限流响应体定制功能，但可通过
拦截自定义状态码，并返回 JSON 提示：
先设置
再用
重定向到内部 location
在
中返回标准 JSON 响应，例如：
这样既保持 HTTP 语义清晰（429 表示频次超限），又能让客户端获得结构化提示。
验证和调试要点
修改配置后需
。验证方式：
用
查看响应头中的
或
行
确保测试请求确实触发限流（如短时间高频访问），否则仍返回正常状态码
注意浏览器可能缓存 503 响应，建议用 curl 或清除缓存测试
若状态码未变化，检查是否遗漏
，或作用域层级错误（如写在了错误的 location 外）
limit_req503 Service Temporarily Unavailablelimit_req_status429 Too Many Requestshttpserverlocationlimit_reqlimit_req_status ;limit_req_status 429;400–599429403444503http {
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_statuslimit_reqlimit_reqerror_pagelimit_req_status 429;error_page 429 = @rate_limited;@rate_limited{"error":"too_many_requests","retry_after":1}nginx -t && nginx -s reloadcurl -IStatusHTTP/1.1limit_req_status