limit_req_status仅能修改HTTP状态码，无法自定义JSON响应体；需配合error_page拦截状态码并用return或proxy_pass生成JSON，同时必须手动设置Content-Type和charset。
不能直接通过 limit_req_status 自定义 JSON 响应体 —— 它只控制 HTTP 状态码，不负责响应内容。想返回结构化 JSON 错误（比如 {"error":"rate_limited","code":429}），必须配合 error_page 和 return 或 proxy_pass 实现。
为什么 limit_req_status 无法设置 JSON 响应体
limit_req_status 是一个纯状态码开关：它只在限流触发时把原本的 503 改成你指定的值（如 429），但 Nginx 仍会用内置的默认错误页（纯文本 HTML）。它不接管响应体生成逻辑，也不支持模板或 JSON 字符串配置。
常见误解是以为设了 limit_req_status 429 就能自动输出 JSON，结果 curl 一测发现还是 text/html 的丑陋页面，甚至 Content-Type 都没变。
正确做法：用 error_page 拦截限流状态并重写响应
核心思路是：让限流触发后返回你指定的状态码 → 用 error_page 把该状态码映射到内部 location → 在该 location 中用 return 直接输出 JSON（或用 proxy_pass 转发给后端生成）。
- 必须先在
limit_req_zone和limit_req中启用，并搭配limit_req_status 429 -
error_page 429 = @rate_limited;—— 注意等号，表示不跳转、直接内部重定向 - 在
location @rate_limited中，用return 429 '{"error":"rate_limited","code":429}\n'; - 务必手动设置
add_header Content-Type "application/json; charset=utf-8";，否则默认是text/plain
示例片段：
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;
<pre class="brush:php;toolbar:false;"> error_page 429 = @rate_limited;
# ... 其他 proxy_pass 等
}
location @rate_limited {
add_header Content-Type "application/json; charset=utf-8";
return 429 '{"error":"rate_limited","code":429,"retry_after":60}\n';
}
}
注意 Content-Type 和字符编码的隐性坑
Nginx 的 return 指令默认不带 Content-Type，浏览器或客户端可能按 text/plain 解析 JSON，导致解析失败。更隐蔽的是：如果 JSON 中含中文（如 "msg":"请求过于频繁"），不加 charset=utf-8 会导致乱码，尤其在旧版 curl 或某些 SDK 中表现不一致。
-
add_header必须写在location @rate_limited内，写在 server 或外层 location 无效（因为return会终止处理流程） - JSON 字符串里的换行符
\n建议保留，部分 HTTP 工具（如 Postman）对无换行的单行 JSON 渲染异常 - 若需动态字段（如当前时间、剩余等待秒数），
return无变量支持，得改用proxy_pass转给一个轻量 endpoint
真正麻烦的不是怎么写这几行配置，而是排查时容易卡在 Content-Type 缺失或 charset 漏写 —— 表现就是 JSON 看起来“对”，但前端 JSON.parse() 报错，或者日志里显示乱码。动手前先用 curl -I 确认响应头是否符合预期。
