HTTP 状态码：五个被长期误解的细节

状态码是 HTTP 里最"看起来简单"的部分——200 成功、404 找不到、500 服务器错误。但真到了排查线上问题的时候，误读状态码会把人带到完全错误的方向。

这篇挑五个最常见、也最容易被误解的点。

一、200 不代表成功

这是最容易吃亏的一条：HTTP 层的成功和业务层的成功是两件事。

一个很常见的写法：

HTTP/1.1 200 OK
Content-Type: application/json

{"code": 40001, "msg": "参数校验失败", "data": null}

HTTP 层面 200，业务层面是失败。如果你的客户端只看 res.ok，就会把失败当成成功，然后拿着 data: null 继续往下走，在几百行之外抛一个毫不相干的异常。

正确的判断要两层都看：

const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const body = await res.json();
if (body.code !== 0) throw new Error(`业务错误 ${body.code}: ${body.msg}`);

这不是设计得不好——把业务错误放在 200 里，可以让网关、CDN、监控不把业务失败统计成"服务不可用"。但作为调用方，必须知道这一层。

判断标准：如果接口文档写了 code 字段，那 HTTP 状态码就只代表"网络层通没通"。

二、401 和 403 不是一回事

两者都表示"你不能访问"，但原因完全不同：

| 码 | 含义 | 该怎么办 |

|---|---|---|

| 401 Unauthorized | 未认证：没带凭证，或凭证失效 | 去登录 / 刷新 token |

| 403 Forbidden | 无权限：认出来了，但不许干这事 | 换账号 / 找管理员开权限 |

这个区分对前端行为影响很大：401 应该跳登录页，403 应该提示"权限不足"，而不是把用户踹去重新登录——他都登录了，再登一次还是没权限。

名字本身也是个历史包袱：401 Unauthorized 的字面意思是"未授权"，但它实际表示"未认证"（Unauthenticated）。真正的"已认证但未授权"是 403。别被这个名字带偏。

三、301 和 302 的差别，浏览器会记住很久

两者都是跳转，但缓存语义完全不同：

• 301 Moved Permanently：永久重定向，浏览器会缓存
• 302 Found：临时重定向，默认不缓存
• 307 / 308：和 302 / 301 类似，但严格保留原请求方法和请求体

301 的坑在于"永久"这两个字是认真的。一旦浏览器缓存了某个 301，后续请求会直接打到新地址，不再经过你的服务器。这时候即使你把服务端配置改回来，缓存过的客户端仍然会跳到旧地址，直到缓存过期。

用 curl 排查这类问题时，很容易被自己骗到——curl 不缓存，所以服务端改了之后 curl 立刻正常，但真实用户的浏览器还在跳。

# 看响应头里有没有缓存指令
curl -I https://example.com/old-path
# 关注：Location、Cache-Control、Expires

实践建议：不确定是不是永久的时候，用 302。 改 301 的成本远高于改 302。

四、304 不是"没有内容"，是"你的缓存还能用"

看到 304 就觉得"接口没返回数据"，是个很常见的误判。

304 Not Modified 出现在协商缓存里：客户端带着 If-None-Match 或 If-Modified-Since 来问"我手上这份还新吗"，服务端回答"还新，别重新下"。

所以 304 的响应体是空的，但客户端应该用本地缓存的内容。

// 浏览器里 fetch 遇到 304 时，拿到的是缓存内容，status 通常仍是 200
const res = await fetch(url, { cache: 'no-cache' });
// res.status 一般不会是 304，这是浏览器帮你处理过的结果

只有在你直接用底层客户端（比如 Node 的 http 模块、或者 curl）时才会真的看到 304。这时候别以为请求失败了——去看本地缓存。

顺带一提：304 不携带响应体，但会携带响应头。有些服务端在 304 里改 Cache-Control，就是为了调整下一次的缓存策略。

五、5xx 里，502 和 504 的原因完全相反

都是网关返回的错误，但方向相反：

| 码 | 含义 | 典型原因 |

|---|---|---|

| 502 Bad Gateway | 网关从上游收到了无效响应 | 上游崩了、返回了乱码、连接被重置 |

| 504 Gateway Timeout | 网关等上游超时 | 上游太慢、卡死、死锁 |

这个差别决定你该查什么：

• 502 → 查上游服务是不是挂了、有没有 OOM、进程还在不在
• 504 → 查上游是不是慢查询、有没有锁等待、超时阈值设得合不合理

如果只看"5xx"，两个都会归到"服务器错误"里，排查方向就模糊了。

还有一个常被忽略的：499（Nginx 自定义）。它表示"客户端主动断开了连接"，通常出现在用户等不及关掉页面、或者上游处理太慢被客户端放弃。这不是服务端的错，但如果你在监控里看到大量 499，说明响应太慢了。

六、小结

五条，归纳成一句话：状态码描述的是"这一层"发生了什么，不代表你关心的那件事成功与否。

• 200 只代表 HTTP 通了，业务结果要看响应体
• 401 是"没登录"，403 是"登录了但不许"
• 301 会被浏览器长期记住，不确定就用 302
• 304 表示"用你的缓存"，不是"没数据"
• 502 是上游坏了，504 是上游慢了

排查的时候养成一个习惯：先看完整响应头和响应体，别只看状态码那一行。 状态码是摘要，真正的信息在头里和体里。

文中示例基于 HTTP/1.1 语义与浏览器实际行为，部分细节在不同客户端实现中略有差异。