必须配合error_page与return实现JSON响应：limit_req_status 429仅改状态码，需在同级location中配置error_page 429 = @rate_limited，并在@rate_limited中用return 429返回JSON及application/json头。
limit_req_status 配置后返回的仍是默认 503 页面？
直接在 limit_req 指令所在上下文中设置 limit_req_status 429，只是改变了 HTTP 状态码，Nginx 默认仍会返回自带的纯文本 503 响应体。要返回 JSON，必须配合 error_page 指令重写响应内容。
如何用 error_page + return 实现 JSON 响应
关键在于：限流触发时 Nginx 内部会生成指定状态码（如 429），此时需捕获该状态并用 return 构造 JSON 响应。注意不能用 proxy_pass 或 fastcgi_pass 中转，否则可能绕过限流或引入延迟。
-
limit_req_status必须设为非 503 的状态码（推荐429），否则和默认错误页冲突 -
error_page 429必须定义在与limit_req相同的 server 或 location 块中，作用域不匹配会导致失效 -
return后需显式指定application/jsonContent-Type，否则前端可能解析失败
limit_req_zone $binary_remote_addr zone=api:10m rate=5r/s;
server {
location /api/ {
limit_req zone=api burst=10 nodelay;
limit_req_status 429;
error_page 429 = @rate_limited;
}
location @rate_limited {
return 429 '{"code":429,"message":"Too many requests"}';
add_header Content-Type "application/json";
}
}
为什么用 named location 而不是直接 return 在原 location
如果在 location /api/ 内直接写 error_page 429 = ... return ...，Nginx 会报错 “directive is not allowed here”，因为 return 在 error_page 的命名 location 外不可用于构造响应体。命名 location 是唯一能安全执行 return 并携带完整响应头/体的机制。
- 不用
rewrite ... break或internallocation，它们无法改变响应状态码 - 不要在
@rate_limited中加proxy_pass，这会让限流判断逻辑和响应生成解耦，增加出错概率 - 若需动态内容（如带时间戳的 JSON），Nginx 原生不支持，得换 OpenResty 或后端兜底
实际部署时容易忽略的兼容性细节
Nginx 1.13.10+ 才完全支持在 error_page 后使用 = 语法跳转到命名 location 并继承状态码；旧版本必须用 error_page 429 /429.json 配合静态文件或后端服务。
- 确认 Nginx 版本：
nginx -v，低于 1.13.10 就别硬套命名 location 方案 -
add_header在error_page命名 location 中有效，但不会继承上级 location 的 headers，所有响应头都得重新声明 - 如果 upstream 返回 429，且你又配了
proxy_intercept_errors on，可能和限流 429 混淆，建议用不同状态码区分（如限流用 429，后端错误用 503）
Nginx 的限流响应定制本质上是“状态码拦截 + 响应重写”，不是扩展点编程；所有逻辑必须压在配置层完成，任何想在其中注入变量或调用外部逻辑的尝试，都会撞上它的设计边界。
