王少冬做后端这些年，我见过太多人在群里甩一张报错截图就开问：“这个 502 到底什么意思？”或者 “接口给我返回 500 了怎么办？”说实话，HTTP 状态码这套东西真要解释起来一点都不神秘——它是 HTTP 协议里服务器给客户端的一个“标准答复体”，用三位数字告诉客户端：这次请求到底成了没有、没成的话问题可能出在哪一层。与其把它当成枯燥的规范条文，不如说这是一套双方都认的“沟通口径”。
这篇文章我想把 HTTP 状态码里最常用的那批拆开揉碎了讲清楚——从分类逻辑到具体语义，从常见踩坑到排查思路，让不同基础的人都能对号入座。不管你是刚入行的前端、后端新手，还是被各种 unexpected status 502 bad gateway 折磨得头秃的运维同学，这篇文章应该都能帮上忙。我还会结合自己实际调试接口、排查线上事故的经历来写，不会只丢一张状态码对照表就完事。
1. 状态码不是报错，是协议里的“约定”
1.1 为什么状态码是 HTTP 协议的基石
很多人第一次接触状态码，是在浏览器控制台里看到红彤彤的 404、500，下意识就觉得“状态码就是报错码”。这个理解不算全错，但格局小了。状态码的本质，是 HTTP 协议为了在“客户端发请求、服务端给响应”这个动作里，给结果做一个标准化的“定性”。它把每一次请求的结果划成三类：成了、没成但还能救、没成且别救。没有这套定性，客户端拿到响应之后只能靠猜，那效率就太低了。
我们平时随口说的 HTTP 协议，最核心的就是请求行、请求头、请求体，以及响应里的状态行、响应头、响应体。状态码就长在状态行里，跟着一个简短的原因短语，比如 HTTP/1.1 200 OK。这个三位数字本身是给程序看的，原因短语是给人看的。之所以用数字，是因为跨语言、跨平台都好解析，三位数字从 100 到 599，涵盖的信息维度足够细。
从 1996 年的 HTTP/1.0 到后来的 HTTP/1.1，状态码的分类框架基本没大变过，后续又陆续补充了一些语义更精确的新码，比如 418、422、429、451 这些。但有一个原则始终没变：状态码必须准确反映请求结果，不能“差不多就行”。我在实际项目里见过不少后端把异常统一返回 200，然后在业务 JSON 里再放一个 code:500，理由是“HTTP 状态码不好控制”。这种做法我强烈不建议——它等于让协议层面的标准信号失效了，客户端、网关、监控系统全都变成瞎子，排查问题只能靠翻日志大海捞针。
1.2 从“五位门牌号”看五个大类
状态码的百位数字代表大类，这个设计特别像门牌号：1 开头的在 1 街区，2 开头的在 2 街区，谁家的门牌一目了然。具体来说：
- 1xx：信息性响应。请求已经被接收，服务器还在处理中。平时看到的机会不多，但涉及到文件上传、协议切换时会出现。
- 2xx：成功。请求已经被接收、理解、并接受。这是最让人安心的街区。
- 3xx：重定向。客户端需要进一步操作才能完成请求，最常见的就是“这地址搬家了，去新地址吧”。
- 4xx：客户端错误。请求的语法或者语义有误，责任基本在发请求的这一侧。
- 5xx：服务端错误。服务器端在处理请求时出了状况，责任在服务提供方。
理解这个分类，对排查问题有立竿见影的帮助。看到 4xx，先别急着骂服务端，回头检查自己的参数、鉴权、URL 拼写；看到 5xx，才需要往服务端代码、数据库、依赖服务那边查。带过团队的同学都懂，如果组里每个人都先分清 4xx 和 5xx，沟通成本能砍掉一大截。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 2xx 与 3xx：正常路径上的状态码
2.1 2xx 系列：请求成功了，具体成功到哪一步
2xx 是整个状态码家族里最讨喜的一批，但你要是以为 2xx 就只有 200，那遇到 201、204 的时候就会犯迷糊。逐个说：
200 OK 是最常见的成功码，表示请求成功且响应体里带着完整数据。GET 查询成功返回 200，POST 提交成功也可以返回 200。但在 RESTful 设计里，200 通常是“读取成功”的代名词。
201 Created 表示资源创建成功，典型场景是 POST 新增数据。我见过很多团队新增接口也返回 200，这不算错，但从语义上讲，201 更能表达“我新建了一个资源”，而且响应体里通常应该带上新资源的 ID 或者访问地址。前端拿到 201 就能明确知道“这是个新增操作”。
204 No Content 代表请求成功了，但是响应体是空的。这个状态码在删除操作和部分更新操作里很常见。比如前端要删一条记录，服务端删除成功后没必要再返回一堆 JSON，直接 204 最干净。前端看到 204 就不要强行去解析响应体了，否则会报解析错误。
206 Partial Content 是断点续传、视频流式加载背后的大功臣。客户端带着 Range 头请求资源的一部分，服务器就返回 206 和对应的分片数据。看视频网站的进度条能随意拖动，靠的就是这个。
还有 202 Accepted，表示请求已经收到，但处理还没完成。异步任务、消息队列的场景经常用。比如你提交了一个批量任务，服务器先返回 202，你过一会儿再查处理结果。这个码在普通业务里用得少，但在系统设计里有很重要的位置。
2.2 3xx 系列：要我换地址吗？
3xx 系列的核心就一个词：重定向。但同样是“换地址”，301 和 302 的差别却能决定一个网站的 SEO 生死。
301 Moved Permanently 是永久重定向。旧地址已经彻底废弃，以后请都去新地址。搜索引擎看到 301，会认为旧页面的权重全部迁移到新页面，这是换域名、http 升级 https 时最标准的做法。
302 Found（历史原因也叫临时重定向）表示这次先临时去别的地址，但旧地址不废弃。登录态失效后跳转登录页、某些支付回调跳转，用的多半是 302。搜索引擎看到 302 不会转移权重，因为它知道原地址还活着。
304 Not Modified 是缓存机制的头号功臣，也是最容易被误解的三位数字。它是“重定向”大类里的一个特殊码：客户端请求资源时带上 If-Modified-Since 或 If-None-Match，服务器发现资源没变，就返回 304，不带上响应体。浏览器一看 304，就直接用本地缓存，省流量、省时间。很多人以为 304 是“错误”，实际上它省了你公司一大笔带宽费。
307 Temporary Redirect 和 308 Permanent Redirect 是 302/301 的“规范加强版”，它们在重定向时保证请求方法和请求体不被改变。比如 POST 请求用 302 重定向，某些老客户端会转成 GET，但 307 能保证仍然是 POST。这个细节在做支付回调、表单提交这类场景时非常关键。
3. 4xx 客户端错误：多半是你请求写错了
3.1 400/401/403/404 四兄弟的区别与实战
4xx 是日常开发里出现频率最高的一批状态码，尤其 400、401、403、404 这四个，长得像，但语义完全不同。很多新手混为一谈，结果排查半天找不到北。
400 Bad Request 表示请求本身有语法错误，服务器表示“看不懂”。常见场景是 JSON 格式写错了、参数类型不匹配、必填字段缺失。我见过大量 HTTP 400 是因为前端把数字类型传成了字符串，或者日期格式不符合后端约定的 yyyy-MM-dd HH:mm:ss。自己在本地用 curl -i 复现一下请求，很容易就能定位。
401 Unauthorized 是“未认证”。直白说就是服务器不知道你是谁。没带 token、token 过期、token 格式不对，统统给 401。注意它的意思是“你没证明你的身份”，不是“你没权限”。我自己排查的时候，看到 401 第一反应永远是去看请求头里的 Authorization 字段到底带没带。
403 Forbidden 是“已认证但没权限”。身份识别通过了，但你没有访问这个资源的权利。401 和 403 的区别可以这样记：401 是“你没带身份证”，403 是“你带了身份证但没门禁卡”。遇到 403，要查的是账号的角色、权限配置，而不是登录状态。
404 Not Found 表示资源不存在。这东西太常见了，URL 拼错、路由没配、资源被删除都会触发。但要注意，有些系统出于安全考虑，会把不存在的资源和没有权限的资源都返回 404，防止攻击者探测目录结构。所以看到 404 不要急着骂前端，先看看是不是被人故意“隐藏”了。
3.2 405/408/409/429/499：容易被当成冷门的状态码
除开四兄弟，还有一批 4xx 状态码，它们平时不算高频，但一出现就都是硬茬。
405 Method Not Allowed：请求方法不对。接口只接受 POST，你发了个 GET，服务器直接回 405。这个比例应对容易，看文档确认接口方法和实际请求方法是否一致就行。但很多框架在路由匹配失败时会返回 404 而不是 405，所以需要自己判断。
408 Request Timeout：请求超时。客户端迟迟没把完整的请求发过去，服务器等不及了。通常和客户端的弱网、大文件上传追不上限有关系。
409 Conflict：资源当前状态和请求冲突。最经典的场景就是并发编辑：两个人同时改同一个文档，后提交的人会收到 409，因为服务端发现版本号对不上。乐观锁机制里，409 是核心信号。
429 Too Many Requests：请求太频繁，被限流了。做 API 网关、爬虫防护、秒杀系统时，这个状态码几乎天天见。它通常会配合响应头 Retry-After 告诉客户端“过几秒再试”。前端看到 429，正确的做法是等一等退避重试，而不是死循环继续刷。
499 Client Closed Request 是 Nginx 特有的状态码，表示“客户端主动断开连接了”。比如你请求一个跑得很慢的接口，前端设置了 10 秒超时，10 秒一到前端断开，Nginx 就会记录一个 499。后端排查问题时看到 499，先想想是不是接口太慢导致客户端等不及。
4. 5xx 服务端错误：问题出在服务端
4.1 500/501/503 的本意与典型场景
5xx 一出现，背锅的方向就很明确：服务端出了问题。但这几个码之间还是有讲究的。
500 Internal Server Error 是最大的“垃圾筐”。代码抛了未捕获的异常、数据库连接池满了、配置加载失败，只要服务器不知道该怎么回复，就统一扔一个 500。它没有特别精确的语义，只能告诉你“服务器内部炸了”。排查 500 的唯一正道是看后端日志，找异常堆栈。别在前端控制台里反复看那个红字，看代码看日志才有用。
501 Not Implemented 表示服务器不支持请求所需要的功能。比如服务器只支持 GET/POST，你却发了一个 DELETE，某些严格实现的服务器会返回 501。这个状态码在普通业务里不太常见，网关、代理服务器上偶尔能看到。
503 Service Unavailable 是“服务暂时不可用”。注意关键词是“暂时”。服务器本身在运行，但状态不对，比如正在重启、负载过高、依赖的数据库连不上。很多网关看到服务健康检查失败，就会自动返回 503 并且不带响应体。这个码的潜台词是“你再等等，可能过一会儿就好了”。它和 500 的区别很微妙：500 是处理请求时崩了，503 是服务整体还没准备好接客。
4.2 502/504 与代理、网关的“爱恨情仇”
502 和 504 是运维场景里最让人头疼的两个码，因为它们经常出现在 Nginx、网关、Docker 反向代理这一层。
502 Bad Gateway 的意思是：网关/代理服务器收到了上游服务器的无效响应。这句话翻译成人话就是：Nginx 把请求转发给了后面的应用服务，但应用服务没有给出正常 HTTP 响应，或者响应格式根本不对。比如后端服务崩溃、端口没监听、防火墙拦截、容器还没启动完成，都会导致 502。我排查 502 的固定套路是三步：先确认后端进程还活着没有，再确认监听端口是否正确，最后看 Nginx 的错误日志里有没有 connect() failed 或者 upstream prematurely closed connection 之类的关键词。
很多工具场景下也能看到 502，比如某些本地代理、Docker 镜像拉取工具返回 unexpected status 502 bad gateway: unknown error。这种时候不要怀疑你的代码，先去看看工具连接的本地地址（比如 127.0.0.1:1572）对应的服务进程是不是挂了，或者证书、配置是不是出了问题。502 的特性决定了它背后的原因可能离你的代码非常远。
504 Gateway Timeout 则是“网关等了太久没等到上游响应”。Nginx 默认转发超时时间通常是 60 秒，后端接口跑了个 90 秒的大查询，Nginx 等不及直接给客户端回 504。这个码的含义很明确：不是连不上，是连上了但太慢。排查方向是给接口做性能优化、加缓存，或者调大代理超时时间。
4.3 状态码的变体与扩展（500.19 等）
标准状态码之外，我们还经常看到状态码带小数点的变体，最典型的就是 Windows 服务器 IIS 的 500.19。HTTP 错误 500.19 - Internal Server Error 表示页面的相关配置数据无效，通常是 web.config 文件里出现了格式错误、文件权限不对、或者 IIS 的某个功能模块没装。这种“扩展状态码”很有价值，因为它把 500 这个大垃圾筐细分出了具体原因。排查 500.19，直接看 IIS 的错误详情，十有八九能锁定到配置文件的某一行。
还有一类“扩展”是网关自定的状态码，比如 520（未知错误）、521（Web 服务器已关闭）、522（连接超时），这些是 Cloudflare 等 CDN 厂商自己加的定义，并不在 HTTP 标准规范里。看到这些码，要意识到你看到的是“边缘节点替你访问源站时的状态”，而不是源站直接回复的状态。
5. 实战：用状态码快速定位线上问题
5.1 一张表看懂“状态码 + 日志”组合排查
状态码最大的价值不是“看一眼知道对错”，而是给排查提供一个高效的入口信号。我习惯把状态码和日志做组合判断，见码先定方向，再去翻对应的日志，而不是盲目地全链路排查。下面这张表是我自己常用的速查表：
| 状态码 | 服务端日志常见特征 | 优先排查方向 |
|---|---|---|
| 400 | 请求体解析失败、参数绑定异常 | 前端传参格式、JSON 合法性、字段类型 |
| 401 | 无 token、token 过期、签名校验失败 | 登录态、请求头 Authorization、密钥配置 |
| 403 | 权限校验不通过、IP 白名单拦截 | 账号角色、权限配置、网关规则 |
| 404 | 路由未匹配、静态文件不存在 | URL 拼写、路由注册、资源部署 |
| 429 | 限流器触发、连接数超阈值 | 限流策略、客户端并发、网关配额 |
| 500 | 未捕获异常、数据库异常、空指针 | 后端异常堆栈、慢 SQL、依赖服务 |
| 502 | upstream connect failed、连接被重置 | 后端进程存活、端口监听、容器状态 |
| 503 | 健康检查失败、应用启动中、连接池满 | 服务注册、负载均衡、依赖组件状态 |
| 504 | upstream timed out、读超时 | 后端接口耗时、代理超时配置、慢查询 |
有了这张表，拿到任何一个状态码，至少能先圈定一个大概的排查范围。比如看到 502，我肯定不会先去看前端代码，因为方向从协议语义上就已经错了。
5.2 代理层、浏览器缓存、开发工具里藏着的信息
状态码虽然只有三位数，但它出现的位置和环境不同，解读出来的味道完全不一样。你在浏览器开发者工具里看到的 200，和你在命令行用 curl 拿到的 200，背后代表的信息可能不同——浏览器可能走的是缓存、带了 Cookie、加了跨域头，而 curl 干干净净，一个多余的头都没有。所以排查问题时，我建议尽量用能精确控制请求的工具来复现：
bash复制# 查看完整响应头，确认状态码和缓存策略
curl -i https://api.example.com/v1/users
# 模拟带 token 的请求，排查 401/403
curl -H "Authorization: Bearer <token>" https://api.example.com/v1/users
很多新手在浏览器里看到 200，就把问题框定在“后端肯定没报错”上，其实不一定。接口返回 200 但业务数据不对，这叫“业务层错误”，和 HTTP 状态码无脑挂钩反而会误导排查。我后来总结出一条经验：HTTP 状态码负责协议层面的对错，业务码负责业务层面的对错，两层要分开看。
顺便提一句，浏览器地址栏直接打开接口地址时，跨域、Cookie、缓存策略都和在代码里用 fetch 发请求不一样。所以调试接口时，别只盯着浏览器开发者工具，多试试 curl、Postman、Apifox 这类独立工具，它们能更大程度还原真实请求链路。
5.3 把状态码当接口设计的“反馈信号”
状态码不光是排查问题的工具，更是接口设计的一部分。好的后端接口，状态码本身就是一份文档。我参与过的项目里，凡是接口设计得清晰的服务，前端同学拿到状态码基本就能判断下一步动作，根本不需要翻文档。比如：
- 登录接口成功返回 200 + token，密码错误返回 401，账号被禁用返回 403；
- 新增资源成功返回 201 + 新资源 ID，参数不合法返回 400 + 具体错误字段；
- 删除资源成功返回 204，资源不存在返回 404。
这套语义一旦统一，前端拦截器就可以做出通用的处理逻辑：收到 401 就清空登录态跳转登录页，收到 403 就提示“没有权限”，收到 429 就做退避重试。代码会清爽很多，排查问题也快很多。
结尾：我自己的习惯
聊了这么多，最后说点掏心窝子的。状态码这东西确实不复杂，但它就像交通标志一样，只有每个人都遵守同一套规则，路上的效率才会高。我自己在实际项目里养成了一个习惯：无论写接口还是排查问题，都会先问一句“这个状态码放在这里，语义对吗？”。遇到拿不准的，就去查规范原文，而不是凭感觉用。踩过几次坑之后你会发现，状态码用得越准确，前后端协作的摩擦越小，线上出问题时的定位速度也越快。希望这篇总结能帮你在下一次看到“500”“502”“403”的时候，少一点慌乱，多一分从容。