Nginx限流默认返回503,但可通过limit_req_status指令自定义为429等状态码;该指令自1.3.15引入,需置于server或location块中与limit_req同级,且作用于对应限流规则。

Nginx 的 limit_req 模块默认在触发限流时返回 503 Service Temporarily Unavailable,但可通过 limit_req_status 指令自定义该状态码,无需修改源码或借助 Lua。
确认 Nginx 版本支持
该指令自 Nginx 1.3.15 起引入,需确保版本 ≥ 1.3.15(推荐 ≥ 1.10.0)。可通过以下命令验证:
nginx -v
在 limit_req_zone 后配置 limit_req_status
该指令必须放在 limit_req 指令所在的作用域中(如 server 或 location 块),且对同一请求生效的 limit_req 生效。写法示例:
limit_req_zone $binary_remote_addr zone=api:10m rate=5r/s;<br>server {<br> location /api/ {<br> limit_req zone=api burst=10 nodelay;<br> limit_req_status 429;<br> }<br>}-
limit_req_status 429表示超出速率限制时返回 429 Too Many Requests(符合 RFC 6585)
配合 error_page 实现更灵活响应
仅改状态码不够?可结合 error_page 返回自定义 JSON 或页面:
limit_req_status 429;<br>error_page 429 = @rate_limited;<br><br>location @rate_limited {<br> add_header Content-Type "application/json";<br> return 429 '{"error":"Too many requests","retry_after":60}';<br>}- error_page 429 = @rate_limited 中的
=表示内部重定向(不改变客户端看到的状态码) - return 可直接输出响应体;若用
proxy_pass,需确保后端能处理 429 - proxy_pass,建议将
limit_req和limit_req_status放在同级 location 内,避免作用域失效
调试与验证方法
启用 Nginx 错误日志并发送高频请求验证是否生效:
error_log /var/log/nginx/rate_limit.log debug;
- limiting requests 字样,并确认响应头中
Status为设定值 - curl -I http://your-domain/api/test,观察返回的
HTTP/1.1 429 - limit_req_status 是否写在正确的 block 内(不能在 http 全局块直接写,需在 server 或 location 中)











