limit_req_status 仅修改限流触发时的http状态码（如设为429），不生成响应体或头；需配合error_page和return才能返回自定义json等完整响应，且必须与limit_req同级配置在server或location块内。

limit_req_status 的作用很明确：它不参与限流逻辑计算，只负责在限流真正触发时，把原本默认返回的 503 Service Unavailable 换成你指定的状态码，比如更语义化的 429 Too Many Requests。它本身不生成响应体、不设置头、不返回内容——这些都得靠后续配合 error_page 和 return（或 proxy_pass）来完成。

限流状态码能设哪些值？

limit_req_status 支持任意标准或自定义 HTTP 状态码，常见选择有：

• 429：最推荐。符合 RFC 6585，客户端（尤其是前端 SDK 或重试库）能自动识别并按 retry-after 头处理
• 503：Nginx 默认值，保留也可，但缺乏业务语义，容易和后端服务不可用混淆
• 403：适合将超限视为“权限拒绝”的场景，例如免费用户调用频次耗尽
• 444：Nginx 特有码，表示直接关闭连接、不发任何响应（静默丢弃），适合风控类强拦截
• 598：非标准但可用的自定义码，便于监控系统单独聚合限流事件

为什么只设 limit_req_status 不够？

因为 limit_req_status 只改状态行，不碰响应体。如果你只写这一行：

limit_req_status 429;

那么触发限流时，Nginx 仍会返回一个空的 429 响应（无 body、无 Content-Type），对 API 客户端极不友好。要返回结构化 JSON，必须补上 error_page 拦截和 return 输出：

• error_page 429 = @rate_limited：等号表示内部重定向，客户端看到的仍是 429，但 Nginx 会跳转到 @rate_limited 这个 location 处理
• location @rate_limited 必须加 internal；否则外部可直接访问该路径
• add_header Content-Type "application/json; charset=utf-8" 显式声明类型，避免客户端解析失败
• return 429 '{"code":429,"message":"Rate limit exceeded","retry_after":60}' 中的 JSON 字符串要用单引号包裹，双引号无需转义

配置位置和作用域要注意什么？

limit_req_status 不能写在 http 全局块里，必须放在 server 或 location 块中，且需与 limit_req 在同一级作用域内，否则会失效：

• ✅ 正确：limit_req 和 limit_req_status 都在同一个 location /api/ { ... } 内
• ❌ 错误：limit_req 在 location 里，limit_req_status 却写在 server 块顶层（子块无法继承父块的 limit_req_status）
• ⚠️ 注意：如果用了 proxy_pass，建议把限流相关指令（limit_req_zone、limit_req、limit_req_status、error_page）都放在同个 location，避免因作用域嵌套导致限流不生效

怎么验证它真的起作用了？

调试关键看两点：状态码是否变了，响应体是否如预期：

• 打开 Nginx 错误日志到 debug 级别：error_log /var/log/nginx/rate_limit.log debug;，观察是否有 limiting requests 日志
• 用 curl 发起高频请求：curl -I http://your-domain/api/test，检查响应头中的 Status 是否为 429
• 去掉 -I 参数，看完整响应体是否是你的 JSON 字符串，并确认 Content-Type 头存在且正确
• 用浏览器开发者工具或 Postman 查看 Network 面板，确认状态码和响应格式一致