HTTP 常见状态码详解：核心语义与适用场景

一、状态码是什么：HTTP 协议的“通用回应语言”

HTTP 是基于“请求—响应”模型的应用层协议。服务端处理完请求后，除了返回数据本身，还必须给出一个三位数字组成的处理结果标识，这就是状态码。可以把它类比为餐厅点餐：顾客报出菜名后，服务员会回应“已收到，后厨马上开始制作”；点了一道已售罄的菜，会被告知“抱歉，这道菜没有了”；若是后厨设备出了故障，则会说明“厨房出了问题，暂时无法出餐”。无论走进哪家餐厅，只要回应规则一致，顾客就能准确理解发生了什么、接下来该怎么做。

HTTP 状态码正是这样一套全球统一的标准，它让浏览器、移动端、网关、监控探针等任何遵循协议的客户端，都能准确理解服务端的处理结果。其价值体现在三个层面：

1. 统一契约：状态码语义由协议规范定义，跨团队、跨语言、跨系统通用，不需要额外文档解释“成功还是失败”。
2. 分层排障：看到 4xx 优先检查调用方参数与凭证，看到 5xx 优先检查服务端与链路，问题定位范围被迅速缩小。
3. 自动化基石：负载均衡健康检查、客户端重试策略、熔断降级、缓存协商等通用机制，都建立在状态码语义之上。

二、五大分类：先建立整体框架

状态码按首位数字分为五大类，理解分类后，具体码值只是分类语义的细化：

• 1xx 信息提示：请求已接收，处理仍在继续，如 100 Continue、101 Switching Protocols，日常业务接口较少直接使用。
• 2xx 成功：请求已被成功接收、理解并处理。
• 3xx 重定向：需要客户端进一步操作（跳转或缓存协商）才能完成请求。
• 4xx 客户端错误：请求本身存在问题（参数、凭证、权限、频率等），服务端拒绝处理。
• 5xx 服务端错误：请求本身合法，但服务端在处理过程中发生故障。

一条便于记忆的主线是：2 开头看“结果”，3 开头看“下一步”，4 开头先查调用方，5 开头先查服务方。

三、2xx 系列：成功不止一个 200

200 OK

最通用的成功码，表示请求成功且响应体中携带处理结果。典型场景是 GET 查询返回资源表示，以及 PUT/PATCH 更新后返回最新数据：

GET /books
响应: 200 OK
[
  { "id": 1, "title": "分布式系统原理" },
  { "id": 2, "title": "网络协议分析" }
]

201 Created

表示请求成功且新资源已被创建，用于 POST 提交创建类操作。最佳实践是同时通过 Location 响应头告知新资源的访问地址，方便客户端直接获取：

POST /books
请求体: { "title": "HTTP 协议详解", "author": "李明" }
处理逻辑:
    newBook = bookRepository.create(request.body)
    设置响应状态为 201
    设置响应头 Location: /books/12

202 Accepted

表示请求已被受理，但尚未处理完成，适用于异步任务场景，例如触发批处理作业、发送异步通知。响应体中可以附带任务查询地址，让客户端后续轮询进度。

204 No Content

表示请求成功，但响应不携带任何实体内容。典型场景包括：删除资源成功、更新成功且客户端本地已持有最新数据。需要特别注意，204 响应不允许包含响应体，如果业务上需要返回更新后的资源，应改用 200。

四、3xx 系列：重定向与缓存协商

301 与 302：永久与临时

• 301 Moved Permanently：资源地址永久变更。适用于站点迁移、接口路径整体调整。浏览器和搜索引擎会将指向永久更新到新地址。
• 302 Found：资源临时位于其他地址。适用于未登录用户跳转登录页、活动期间临时切换入口等场景，原地址日后仍会恢复使用。

307 与 308：保持请求方法

307/308 是 302/301 的严格版本，要求客户端重定向时不得更改请求方法，避免 POST 请求被降级为 GET 导致请求体丢失。涉及表单提交或接口转发时，应优先使用这两个码值。

304 Not Modified：条件请求缓存

客户端携带 If-None-Match（配合 ETag）或 If-Modified-Since 发起条件请求，若资源未变化，服务端仅返回 304，不传输正文。这能显著节省带宽，适用于静态资源加载、列表类接口的增量刷新等场景。

五、4xx 系列：把“问题出在调用方”说清楚

400 Bad Request

参数缺失、格式非法、业务校验不通过时使用。响应体应尽量给出具体到字段的错误说明，避免客户端盲目重试。

401 与 403：认证与权限要区分

• 401 Unauthorized：未通过身份认证，如未登录、令牌缺失或已过期，通常配合 WWW-Authenticate 头说明认证方式。
• 403 Forbidden：身份已确认，但没有访问该资源的权限。

二者的区分直接影响前端交互策略：收到 401 应引导用户重新登录，收到 403 则提示无权限。若混用，会造成大量难以排查的交互问题。

404 Not Found

请求的资源不存在。在需要防范资源枚举探测的场景下，也可以将 401/403 统一降级为 404，避免向未授权方暴露资源是否存在。

405 Method Not Allowed

URI 存在但不支持当前 HTTP 方法时返回，例如对只读接口发起 DELETE。响应应携带 Allow 头，列出该资源支持的方法集合。

409 Conflict

请求与资源当前状态冲突，典型如唯一键重复注册、并发修改引发版本冲突。

415 与 429

• 415 Unsupported Media Type：请求的 Content-Type 服务端无法处理，例如接口要求 JSON 却上传了其他格式。
• 429 Too Many Requests：触发限流策略，可配合 Retry-After 头告知客户端合理的重试间隔。

在工程实现上，主流 Web 框架普遍支持“抛出携带状态码的业务异常，由全局异常处理器统一转换为响应”的编程模式，使业务代码保持简洁、状态码语义不散落在各处：

GET /books/999
处理逻辑:
    book = repository.findById(999)
    if book == null:
        抛出携带 404 的业务异常
        由统一异常处理器转换为响应
响应: 404 Not Found
{ "code": "BOOK_NOT_FOUND", "message": "请求的图书不存在" }

六、5xx 系列：定位故障发生在哪一层

500 Internal Server Error

应用内部出现未预期的异常，如空引用、数据库语句错误、依赖服务抛错未被捕获。生产环境中应通过全局兜底处理返回 500，并避免将堆栈等内部细节直接暴露给客户端。

502 Bad Gateway

网关或代理从上游收到了无效响应，或上游直接断开连接。出现 502 通常意味着应用进程崩溃、端口未监听或正处于重启过程。

503 Service Unavailable

服务暂时不可用，常见于过载保护、滚动发布、维护窗口等主动保护场景，可配合 Retry-After 头告知恢复预期。

504 Gateway Timeout

网关等待上游响应超时，多由慢查询、下游阻塞、线程池耗尽等性能问题引发。

实践中有一条高效的排障经验：502/504 指向“网关与上游之间”的链路问题，500 指向应用自身逻辑问题，503 多为主动保护行为。根据具体码值即可快速缩小排查范围。

七、设计要点与常见误区

1. 警惕“一律返回 200”的反模式。把所有结果都塞进 200 响应体，会导致网关与监控系统无法按状态码统计错误率，通用的重试、熔断、缓存组件失去判断依据，客户端也必须解析响应体才能得知成败。
2. 状态码与业务错误码双层互补。HTTP 状态码表达“传输与处理层面的结果”，响应体中的业务码表达“业务规则的细分原因”，二者配合而非相互替代。
3. 结合幂等性选择码值。PUT/PATCH/DELETE 等幂等操作重复执行应返回稳定结果；POST 创建遇到唯一性冲突时，可用 409 表达矛盾。
4. 善用缓存协商。合理使用 304、ETag 等机制，可显著降低带宽成本与服务端压力。
5. 纳入监控告警体系。在 API 网关、云监控等通用产品能力中，按状态码维度统计成功率与错误率是服务健康度观测的基础手段，百度智能云等云平台的相关通用能力也以此作为核心指标支撑告警与容量规划。团队应将 5xx 占比、4xx 突增纳入核心监控面板。
6. 注意安全细节。认证失败应返回 401 而非 500；错误信息避免泄露内部实现与敏感路径。

八、小结

状态码是 API 递给调用方的第一层“表情”。掌握“2xx 看结果、3xx 看跳转、4xx 查调用方、5xx 查服务端”的分类主线，再针对 200/201/204、301/302/304、400/401/403/404/429、500/502/503/504 这些高频码值建立条件反射，就能在接口设计与线上排障中做到语义准确、响应一致。让每一个状态码都“言符其实”，是构建高质量、可维护 API 服务的基本功。