nginx限流应统一返回429状态码并配结构化json响应体：limit_conn用limit_conn_status，limit_req用error_page间接转换；通过named location + return实现json提示，需启用proxy_intercept_errors、注意文件大小与引号格式，并添加retry-after等响应头提升友好性。
接口限流触发后返回友好的错误提示，核心是两件事：一是把默认的 503 改成语义更清晰的状态码（比如 429），二是返回结构化、可读性强的响应体（如 JSON）。Nginx 原生不支持直接“一键配置”，但通过组合指令可以稳定实现。
用 limit_conn_status 或 error_page 统一返回 429 状态码
限流分两类：连接数限制（limit_conn）和请求速率限制（limit_req），它们对状态码的支持方式不同：
-
limit_conn 支持
limit_conn_status 429（Nginx ≥ 1.13.10），可直接生效，无需绕路 -
limit_req 不支持
limit_req_status指令（该指令不存在），必须用error_page 503 =429 @named方式间接转换
推荐统一用 429，因为它是 RFC 标准定义的 “Too Many Requests”，前端容易识别、监控系统不会误判为服务故障。
返回结构化 JSON 提示（如 {"code":429,"msg":"请求太频繁"}）
仅改状态码还不够，用户或前端需要明确知道发生了什么。Nginx 不能在限流时自动注入 JSON，但可通过命名 location + return 实现：
- 在限流 location 中加
error_page 429 = @rate_limited - 单独定义
location @rate_limited { internal; default_type application/json; return 429 '{"code":429,"msg":"请求过于频繁，请稍后再试","retry_after":60}'; } -
internal防止被外部直接访问，default_type确保浏览器正确解析为 JSON（漏掉会下载文件）
确保错误页真正生效的四个关键点
很多配置写了却没效果，通常卡在这几个环节：
- 如果是反向代理（如转发到 Node.js/Java 后端），必须开启
proxy_intercept_errors on;，否则后端返回的 4xx/5xx 不会被 Nginx 拦截 - 静态 JSON 文件路径要准确，
root指向目录，Nginx 自动拼接；用alias易出错 - 自定义错误页文件大小不能小于 512 字节（尤其旧版 IE），否则浏览器显示兜底页
- JSON 字符串必须用单引号包裹，双引号需转义，且不能换行，否则配置加载失败
补充友好性：加响应头和重试建议
除了正文，还可以增强用户体验和调试效率：
- 用
add_header Retry-After "60"告诉客户端多久后可重试（单位秒） - 加
X-RateLimit-Reason: "req_rate_exceeded"区分是请求频次超限还是连接数超限 - 若需动态内容（如带当前时间戳），Nginx 原生不支持，建议交由后端统一处理，或升级到 OpenResty
