应将限流状态码设为429并自定义JSON响应体，通过limit_req_status设状态码、error_page跳转至named location，用return返回含code/message/retry_after字段的JSON，避免遗漏等号或proxy_pass。
可以通过 limit_req_status 指令配合 error_page 和自定义响应体，实现对限流触发时 HTTP 状态码和响应内容的完全控制，从而让前端能统一识别、解析并拦截限流响应。
明确限流状态码并绑定自定义响应
Nginx 默认在限流触发时返回 503，但该状态码语义宽泛（服务不可用），不利于前端精准判断是否为“被限流”。建议显式设置为更语义化的状态码，例如 429（Too Many Requests）：
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
location /api/ {
limit_req zone=api burst=5 nodelay;
limit_req_status 429; # 关键：覆盖默认 503
error_page 429 = @rate_limited;
}
<pre class="brush:php;toolbar:false;">location @rate_limited {
add_header Content-Type "application/json; charset=utf-8";
return 429 '{"code":429,"message":"请求过于频繁，请稍后重试","retry_after":60}';
}}
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
确保响应体结构与前端拦截逻辑对齐
前端通常通过 Axios、Fetch 等库全局拦截错误响应。为便于统一处理，响应体应满足以下要求：
立即学习“前端免费学习笔记（深入）”；
-
固定字段：如
code（数值型错误码）、message（用户提示）、retry_after（可选，单位秒，用于指导重试时机） -
无 HTML 或纯文本：避免前端 JSON.parse 失败；Nginx 的
return指令需显式指定Content-Type -
支持国际化占位（可选）：若需多语言，可由后端动态生成响应体，或通过 Nginx 变量注入简单上下文（如
$limit_req_status）
避免常见配置陷阱
-
不要遗漏
=符号：写成error_page 429 @rate_limited;（无等号）会导致重定向而非内部跳转，状态码仍为 302，破坏前端拦截逻辑 -
不要在
@rate_limited中使用proxy_pass：这会引入额外延迟和失败风险；限流响应必须轻量、本地生成 -
注意变量作用域：
$binary_remote_addr等变量在@named_location中不可用；如需携带客户端信息（如 IP），需提前用map提取到全局变量中
前端拦截示例（以 Axios 为例）
利用响应拦截器识别 429 并触发统一提示或退避策略：
axios.interceptors.response.use(
res => res,
error => {
if (error.response?.status === 429) {
const data = error.response.data;
message.warning(data.message || '操作太频繁了');
// 可选：自动延时重试
if (data.retry_after) {
setTimeout(() => { /* 重试逻辑 */ }, data.retry_after * 1000);
}
return Promise.reject(error);
}
return Promise.reject(error);
}
); 
