limit_conn_status 可自定义连接超限时的HTTP状态码（如429），需配合limit_conn_zone和limit_conn使用，仅作用于并发连接限制，不支持if块且要求Nginx 1.13.10+版本。
可以通过 limit_conn_status 指令直接设置限流触发时返回的 HTTP 状态码，默认是 503，但你可以改成 429、403 或其他符合业务语义的码，让前端更容易识别和处理限流场景。
配置 limit_conn_status 的基本写法
该指令必须放在 http、server 或 location 块中，且需配合 limit_conn_zone 和 limit_conn 使用。它只影响由 limit_conn 触发的连接数限制，不作用于 limit_req（请求速率限制）。
- 在
http块中定义共享内存区域和状态码：
http {
limit_conn_zone $binary_remote_addr zone=addr:10m;
<pre class="brush:php;toolbar:false;"># 全局设定限流返回码为 429 Too Many Requests
limit_conn_status 429;
server {
location /api/ {
limit_conn addr 10; # 单 IP 最多 10 个并发连接
proxy_pass http://backend;
}
}}
为什么推荐用 429 而不是 503
429 是 RFC 6585 明确定义的“Too Many Requests”状态码，语义清晰，前端可统一捕获并做重试退避、提示用户或降级逻辑；而 503 表示服务不可用，容易误导监控系统或触发错误告警。
立即学习“前端免费学习笔记（深入）”；
- 主流前端框架（如 Axios、Fetch）能通过
response.status === 429精准判断限流 - API 网关、OpenAPI 文档、错误码规范中更倾向将 429 专用于频控/连接数超限场景
- 某些 CDN 或 WAF 也会识别 429 并提供原生限流日志或自动重试支持
与 limit_req_status 配合使用实现全链路限流标识
如果同时用了连接数限制（limit_conn）和请求速率限制（limit_req），建议分别设置不同状态码，便于前端区分是“连接打满了”还是“请求发太快了”。
-
limit_conn_status 429：表示客户端并发连接数超标（如 WebSocket 长连、HTTP/1.1 复用连接） -
limit_req_status 429或400：表示单位时间请求数超限（注意：两个指令可共用 429，但需靠响应头或 body 区分原因） - 可通过
add_header X-RateLimit-Reason "conn_exceeded"补充说明，增强可观测性
注意事项与常见问题
该指令在 Nginx 1.13.10+ 版本才正式支持，旧版本（如 1.12.x）不识别，会忽略并默认返回 503。生产环境务必确认版本兼容性。
- 不能在 if 块中使用，属于上下文敏感指令
- 若未显式配置，所有
limit_conn触发点都返回 503，无法单独为某个 location 覆盖 - 返回体内容仍由 Nginx 默认错误页决定，如需自定义响应体（如 JSON 格式），需配合
error_page 429 /429.json和静态文件或后端兜底
