【架构】-- HTTP 响应状态码详解

类别	范围	说明	常见状态码
信息响应	100-199	临时响应，表示请求已接收，继续处理	100, 101, 102, 103
成功响应	200-299	请求已成功处理	200, 201, 202, 204, 206
重定向消息	300-399	需要进一步操作以完成请求	301, 302, 303, 304, 307, 308
客户端错误响应	400-499	请求包含错误语法或无法完成	400, 401, 403, 404, 405, 429
服务端错误响应	500-599	服务器处理请求时发生错误	500, 502, 503, 504

信息响应 (100-199)

信息响应状态码表示请求已接收，客户端应继续处理。

状态码	名称	含义	使用场景	状态
100	Continue	这个临时响应表明，迄今为止的所有内容都是可行的，客户端应该继续请求，如果已经完成，则忽略它	客户端发送带有 `Expect: 100-continue` 头的请求时，服务器会先返回此状态码，表示可以继续发送请求体	✅ 标准
101	Switching Protocols	该代码是响应客户端的 `Upgrade` 请求头发送的，指明服务器即将切换的协议	用于协议升级，例如从 HTTP/1.1 升级到 WebSocket	✅ 标准
102	Processing (WebDAV)	此代码表示服务器已收到并正在处理该请求，但当前没有响应可用	主要用于 WebDAV 扩展，表示请求正在处理中，可以防止客户端超时	✅ WebDAV
103	Early Hints	此状态代码主要用于与 `Link` 链接头一起使用，以允许用户代理在服务器准备响应阶段时开始预加载资源	用于性能优化，允许浏览器提前开始加载资源	✅ 标准

成功响应 (200-299)

成功响应状态码表示请求已成功处理。

状态码	名称	含义	使用场景	HTTP 方法对应
200	OK	请求成功。成功的含义取决于 HTTP 方法： - `GET`: 资源已被提取并在消息正文中传输 - `HEAD`: 实体标头位于消息正文中 - `PUT` 或 `POST`: 描述动作结果的资源在消息体中传输 - `TRACE`: 消息正文包含服务器收到的请求消息	最常用的成功状态码，适用于大多数成功的请求	GET, HEAD, PUT, POST, TRACE
201	Created	该请求已成功，并因此创建了一个新的资源。这通常是在 POST 请求，或是某些 PUT 请求之后返回的响应	创建新资源后返回，通常响应头中包含 `Location` 字段，指向新创建的资源	POST, PUT
202	Accepted	请求已经接收到，但还未响应，没有结果。意味着不会有一个异步的响应去表明当前请求的结果，预期另外的进程和服务去处理请求，或者批处理	异步处理场景、批量操作、需要长时间处理的任务	POST, PUT, DELETE
203	Non-Authoritative Information	服务器已成功处理了请求，但返回的实体头部元信息不是在原始服务器上有效的确定集合，而是来自本地或者第三方的拷贝	使用缓存或代理服务器时，当返回的信息可能不是最新版本时使用	GET
204	No Content	对于该请求没有的内容可发送，但头部字段可能有用。用户代理可能会用此时请求头部信息来更新原来资源的头部缓存字段	DELETE 请求成功但无需返回内容、更新操作成功但无需返回数据、表单提交后的成功响应	DELETE, PUT, PATCH
205	Reset Content	告诉用户代理重置发送此请求的文档	表单提交后，需要清空表单内容时使用	POST
206	Partial Content	当从客户端发送 `Range` 范围标头以只请求资源的一部分时，将使用此响应代码	断点续传、视频/音频流式传输、大文件分块下载	GET
207	Multi-Status (WebDAV)	对于多个状态代码都可能合适的情况，传输有关多个资源的信息	WebDAV 协议中，一次请求操作多个资源时使用	PROPFIND, PROPPATCH
208	Already Reported (WebDAV)	在 DAV 里面使用 `<dav:propstat>` 响应元素以避免重复枚举多个绑定的内部成员到同一个集合	WebDAV 协议专用	PROPFIND
226	IM Used (HTTP Delta encoding)	服务器已经完成了对资源的 `GET` 请求，并且响应是对当前实例应用的一个或多个实例操作结果的表示	HTTP Delta 编码场景	GET

重定向消息 (300-399)

重定向状态码表示需要进一步操作以完成请求。

状态码	名称	含义	使用场景	是否保持方法	缓存性	状态
300	Multiple Choice	请求拥有多个可能的响应。用户代理或者用户应当从中选择一个	内容协商场景，当服务器提供多个资源版本时	-	不缓存	✅ 标准
301	Moved Permanently	请求资源的 URL 已永久更改。在响应中给出了新的 URL	网站永久迁移、URL 结构重构、域名变更	可能改变	永久缓存	✅ 标准
302	Found	此响应代码表示所请求资源的 URI 已暂时更改。未来可能会对 URI 进行进一步的改变	临时重定向、维护期间的页面跳转	可能改变	不缓存	✅ 标准
303	See Other	服务器发送此响应，以指示客户端通过一个 GET 请求在另一个 URI 中获取所请求的资源	POST 请求后重定向到结果页面，避免重复提交	改为 GET	不缓存	✅ 标准
304	Not Modified	这是用于缓存的目的。它告诉客户端响应还没有被修改，因此客户端可以继续使用相同的缓存版本的响应	条件请求（If-Modified-Since, If-None-Match）、缓存验证、减少带宽使用	-	使用缓存	✅ 标准
305	Use Proxy	在 HTTP 规范中定义，以指示请求的响应必须被代理访问。由于对代理的带内配置的安全考虑，它已被弃用	-	-	-	⚠️ 已弃用
306	unused	此响应代码不再使用；它只是保留。它曾在 HTTP/1.1 规范的早期版本中使用过	-	-	-	❌ 不再使用
307	Temporary Redirect	服务器发送此响应，以指示客户端使用在前一个请求中使用的相同方法在另一个 URI 上获取所请求的资源。与 `302 Found` 具有相同的语义，但用户代理不能更改所使用的 HTTP 方法	临时重定向、需要保持 HTTP 方法不变的重定向	必须保持	不缓存	✅ 标准
308	Permanent Redirect	这意味着资源现在永久位于由 `Location:` HTTP Response 标头指定的另一个 URI。与 `301 Moved Permanently` 具有相同的语义，但用户代理不能更改所使用的 HTTP 方法	永久重定向、需要保持 HTTP 方法不变的永久重定向	必须保持	永久缓存	✅ 标准

重定向状态码对比

特性	301	302	303	307	308
永久/临时	永久	临时	临时	临时	永久
保持 HTTP 方法	可能改变	可能改变	改为 GET	必须保持	必须保持
缓存性	永久缓存	不缓存	不缓存	不缓存	永久缓存
使用频率	高	高	中	中	低

客户端错误响应 (400-499)

客户端错误响应表示请求包含错误语法或无法完成。

状态码	名称	含义	使用场景	常见原因
400	Bad Request	由于被认为是客户端错误（例如，错误的请求语法、无效的请求消息帧或欺骗性的请求路由），服务器无法或不会处理请求	请求格式错误、参数缺失或格式不正确、JSON 解析错误	请求语法错误、参数错误
401	Unauthorized	虽然 HTTP 标准指定了"unauthorized"，但从语义上来说，这个响应意味着"unauthenticated"。也就是说，客户端必须对自身进行身份验证才能获得请求的响应	需要登录但未提供认证信息、认证信息无效或过期	未认证、认证失败
402	Payment Required	此响应代码保留供将来使用。创建此代码的最初目的是将其用于数字支付系统，但是此状态代码很少使用，并且不存在标准约定	-	-
403	Forbidden	客户端没有访问内容的权限；也就是说，它是未经授权的，因此服务器拒绝提供请求的资源。与 `401 Unauthorized` 不同，服务器知道客户端的身份	已认证但权限不足、IP 地址被禁止、资源访问受限	权限不足、访问被禁止
404	Not Found	服务器找不到请求的资源。在浏览器中，这意味着无法识别 URL。在 API 中，这也可能意味着端点有效，但资源本身不存在	URL 不存在、资源已被删除、路由配置错误	资源不存在、URL 错误
405	Method Not Allowed	服务器知道请求方法，但目标资源不支持该方法。例如，API 可能不允许调用 `DELETE` 来删除资源	使用了不支持的 HTTP 方法、RESTful API 中方法不匹配	HTTP 方法不支持
406	Not Acceptable	当 web 服务器在执行服务端驱动型内容协商机制后，没有发现任何符合用户代理给定标准的内容时，就会发送此响应	内容协商失败、客户端请求的格式服务器无法提供	内容格式不支持
407	Proxy Authentication Required	类似于 `401 Unauthorized` 但是认证需要由代理完成	需要通过代理服务器认证	代理认证失败
408	Request Timeout	此响应由一些服务器在空闲连接上发送，即使客户端之前没有任何请求。这意味着服务器想关闭这个未使用的连接	请求超时、连接空闲时间过长、服务器关闭未使用的连接	请求超时
409	Conflict	当请求与服务器的当前状态冲突时，将发送此响应	资源冲突（如并发更新）、版本冲突、数据不一致	资源冲突
410	Gone	当请求的内容已从服务器中永久删除且没有转发地址时，将发送此响应。客户端需要删除缓存和指向资源的链接	资源永久删除、限时服务已过期	资源已永久删除
411	Length Required	服务端拒绝该请求因为 `Content-Length` 头部字段未定义但是服务端需要它	服务器要求必须提供 `Content-Length` 头	缺少 Content-Length
412	Precondition Failed	客户端在其头文件中指出了服务器不满足的先决条件	条件请求失败（If-Match, If-None-Match, If-Modified-Since 等）、乐观锁冲突	条件不满足
413	Payload Too Large	请求实体大于服务器定义的限制。服务器可能会关闭连接，或在标头字段后返回重试 `Retry-After`	上传文件过大、请求体超过限制	请求体过大
414	URI Too Long	客户端请求的 URI 比服务器愿意接收的长度长	URL 过长、GET 请求参数过多	URI 过长
415	Unsupported Media Type	服务器不支持请求数据的媒体格式，因此服务器拒绝请求	Content-Type 不支持、文件格式不支持	媒体类型不支持
416	Range Not Satisfiable	无法满足请求中 `Range` 标头字段指定的范围。该范围可能超出了目标 URI 数据的大小	请求的范围无效、范围超出文件大小	范围请求无效
417	Expectation Failed	此响应代码表示服务器无法满足 `Expect` 请求标头字段所指示的期望	服务器无法满足 `Expect: 100-continue` 等期望	期望不满足
418	I'm a teapot	服务端拒绝用茶壶煮咖啡。这是一个笑话状态码，典故来源茶壶冲泡咖啡	幽默场景，实际项目中很少使用	-
421	Misdirected Request	请求被定向到无法生成响应的服务器。这可以由未配置为针对请求 URI 中包含的方案和权限组合生成响应的服务器发送	HTTP/2 连接复用场景中的服务器选择错误	服务器选择错误
422	Unprocessable Entity (WebDAV)	请求格式正确，但由于语义错误而无法遵循	数据验证失败、业务逻辑错误、WebDAV 协议	语义错误
423	Locked (WebDAV)	正在访问的资源已锁定	WebDAV 协议中资源被锁定时	资源被锁定
424	Failed Dependency (WebDAV)	由于前一个请求失败，请求失败	WebDAV 协议中，依赖的请求失败时	依赖请求失败
425	Too Early	表示服务器不愿意冒险处理可能被重播的请求	防止重放攻击	请求过早
426	Upgrade Required	服务器拒绝使用当前协议执行请求，但在客户端升级到其他协议后可能愿意这样做	需要协议升级	协议版本不支持
428	Precondition Required	源服务器要求请求是有条件的。此响应旨在防止'丢失更新'问题	防止并发更新冲突、要求条件请求头	缺少条件头
429	Too Many Requests	用户在给定的时间内发送了太多请求（"限制请求速率"）	API 限流、防止 DDoS 攻击、速率限制	请求过于频繁
431	Request Header Fields Too Large	服务器不愿意处理请求，因为其头字段太大。在减小请求头字段的大小后，可以重新提交请求	请求头过大（如 Cookie 过多）	请求头过大
451	Unavailable For Legal Reasons	用户代理请求了无法合法提供的资源，例如政府审查的网页	法律原因无法访问、内容审查、版权问题	法律限制

常见客户端错误对比

状态码	认证状态	含义	区别
401	未认证	需要身份验证	客户端未提供认证信息或认证失败
403	已认证	权限不足	客户端已认证，但没有访问权限
404	-	资源不存在	资源不存在或 URL 错误
410	-	资源已永久删除	资源曾经存在但已永久删除

服务端错误响应 (500-599)

服务端错误响应表示服务器处理请求时发生错误。

状态码	名称	含义	使用场景	常见原因
500	Internal Server Error	服务器遇到了不知道如何处理的情况	服务器内部错误、未捕获的异常、配置错误	服务器内部错误
501	Not Implemented	服务器不支持请求方法，因此无法处理。服务器需要支持的唯二方法（因此不能返回此代码）是 `GET` 和 `HEAD`	请求方法未实现、功能未开发	功能未实现
502	Bad Gateway	此错误响应表明服务器作为网关需要得到一个处理这个请求的响应，但是得到一个错误的响应	网关服务器错误、上游服务器无响应、代理服务器问题	网关错误
503	Service Unavailable	服务器没有准备好处理请求。常见原因是服务器因维护或重载而停机	服务器维护中、服务器过载、临时不可用	服务不可用
504	Gateway Timeout	当服务器充当网关且无法及时获得响应时，会给出此错误响应	网关超时、上游服务器响应超时	网关超时
505	HTTP Version Not Supported	服务器不支持请求中使用的 HTTP 版本	使用了服务器不支持的 HTTP 版本	HTTP 版本不支持
506	Variant Also Negotiates	服务器存在内部配置错误：所选的变体资源被配置为参与透明内容协商本身，因此不是协商过程中的适当终点	服务器配置错误	配置错误
507	Insufficient Storage (WebDAV)	无法在资源上执行该方法，因为服务器无法存储成功完成请求所需的表示	存储空间不足、WebDAV 协议	存储空间不足
508	Loop Detected (WebDAV)	服务器在处理请求时检测到无限循环	WebDAV 协议中检测到循环引用	循环引用
510	Not Extended	服务器需要对请求进行进一步扩展才能完成请求	需要扩展协议	需要扩展
511	Network Authentication Required	指示客户端需要进行身份验证才能获得网络访问权限	公共 Wi-Fi 需要认证、网络访问控制	网络认证

常见服务端错误对比

状态码	错误类型	是否可恢复	建议操作
500	服务器内部错误	可能	检查服务器日志，修复代码错误
502	网关错误	可能	检查上游服务器状态，检查网关配置
503	服务不可用	是	等待服务恢复，检查 `Retry-After` 头
504	网关超时	可能	检查上游服务器响应时间，增加超时设置

状态码快速参考表

最常用的状态码

状态码	名称	类别	使用频率	说明
200	OK	成功	⭐⭐⭐⭐⭐	请求成功
201	Created	成功	⭐⭐⭐⭐	资源创建成功
204	No Content	成功	⭐⭐⭐	操作成功但无返回内容
301	Moved Permanently	重定向	⭐⭐⭐⭐	永久重定向
302	Found	重定向	⭐⭐⭐⭐	临时重定向
304	Not Modified	重定向	⭐⭐⭐⭐	使用缓存
400	Bad Request	客户端错误	⭐⭐⭐⭐⭐	请求错误
401	Unauthorized	客户端错误	⭐⭐⭐⭐⭐	未认证
403	Forbidden	客户端错误	⭐⭐⭐⭐	权限不足
404	Not Found	客户端错误	⭐⭐⭐⭐⭐	资源不存在
429	Too Many Requests	客户端错误	⭐⭐⭐	请求过于频繁
500	Internal Server Error	服务端错误	⭐⭐⭐⭐⭐	服务器内部错误
502	Bad Gateway	服务端错误	⭐⭐⭐	网关错误
503	Service Unavailable	服务端错误	⭐⭐⭐⭐	服务不可用
504	Gateway Timeout	服务端错误	⭐⭐⭐	网关超时

按 HTTP 方法推荐的状态码

HTTP 方法	成功状态码	常见错误状态码	说明
GET	200, 206	400, 404, 500	获取资源
POST	201, 200, 204	400, 401, 403, 409, 422, 500	创建资源
PUT	200, 204	400, 401, 403, 404, 409, 500	更新资源（完整）
PATCH	200, 204	400, 401, 403, 404, 409, 422, 500	更新资源（部分）
DELETE	200, 204	400, 401, 403, 404, 409, 500	删除资源
HEAD	200	400, 404, 500	获取响应头
OPTIONS	200, 204	400, 405, 500	获取允许的方法

最佳实践

1. 状态码选择指南

场景	推荐状态码	说明
资源获取成功	200	标准成功响应
资源创建成功	201	创建操作成功，通常包含 `Location` 头
资源更新成功	200 或 204	200 返回更新后的资源，204 不返回内容
资源删除成功	200 或 204	200 返回删除确认，204 不返回内容
请求格式错误	400	提供详细的错误信息
需要认证	401	返回 `WWW-Authenticate` 头
权限不足	403	已认证但无权限
资源不存在	404	不要泄露敏感信息
请求过于频繁	429	返回 `Retry-After` 头
服务器错误	500	记录日志，不暴露敏感信息

2. 错误响应格式建议

字段	说明	示例
`status`	HTTP 状态码	400
`error`	错误类型	"Bad Request"
`message`	错误描述	"请求参数格式错误"
`details`	详细错误信息（可选）	{"field": "email", "message": "邮箱格式不正确"}
`timestamp`	错误时间戳（可选）	"2025-01-15T10:30:00Z"
`path`	请求路径（可选）	"/api/users"

示例 JSON 响应：

复制代码

{
  "status": 400,
  "error": "Bad Request",
  "message": "请求参数格式错误",
  "details": {
    "field": "email",
    "message": "邮箱格式不正确"
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "path": "/api/users"
}

3. 缓存策略

状态码	缓存性	Cache-Control 建议	说明
200	可缓存	`max-age=3600`	根据内容设置合适的缓存时间
201	不缓存	`no-cache`	新创建的资源
204	不缓存	`no-cache`	无内容响应
301	永久缓存	`max-age=31536000`	永久重定向
302	不缓存	`no-cache`	临时重定向
304	使用缓存	-	缓存验证成功
404	短期缓存	`max-age=300`	避免重复请求
500	不缓存	`no-cache`	服务器错误
502	不缓存	`no-cache`	网关错误
503	不缓存	`no-cache, retry-after=60`	服务不可用

4. 安全最佳实践

实践	说明	示例
隐藏资源存在性	对未授权用户使用 404 而不是 403	防止信息泄露
不暴露敏感信息	500 错误不返回数据库错误详情	只返回通用错误信息
合理使用 401 和 403	401 表示未认证，403 表示已认证但无权限	明确区分认证和授权
实施速率限制	使用 429 状态码	防止 DDoS 攻击
记录详细日志	服务器端记录详细错误，客户端只返回必要信息	便于调试但不泄露信息

5. RESTful API 设计规范

操作	HTTP 方法	成功状态码	错误状态码	说明
获取资源列表	GET	200	400, 500	返回资源数组
获取单个资源	GET	200	404, 500	返回单个资源对象
创建资源	POST	201	400, 401, 403, 409, 422, 500	返回创建的资源
更新资源（完整）	PUT	200/204	400, 401, 403, 404, 409, 500	替换整个资源
更新资源（部分）	PATCH	200/204	400, 401, 403, 404, 409, 422, 500	部分更新资源
删除资源	DELETE	200/204	400, 401, 403, 404, 409, 500	删除资源
获取允许的方法	OPTIONS	200/204	400, 500	返回 `Allow` 头

6. 常见错误处理模式

错误类型	状态码	响应头	响应体
认证失败	401	`WWW-Authenticate: Bearer`	错误信息
权限不足	403	-	权限说明
资源不存在	404	-	错误信息
方法不允许	405	`Allow: GET, POST`	允许的方法列表
请求体过大	413	`Retry-After: 60`	错误信息和限制说明
请求过于频繁	429	`Retry-After: 60`	错误信息和重试时间
服务不可用	503	`Retry-After: 300`	错误信息和预计恢复时间

参考资料

资源	链接	说明
MDN Web Docs	HTTP 响应状态码	官方文档，本文档主要参考
RFC 7231	HTTP/1.1 Semantics and Content	HTTP/1.1 语义和内容规范
RFC 2616	HTTP/1.1	HTTP/1.1 原始规范
IANA Registry	HTTP Status Code Registry	官方状态码注册表
维基百科	HTTP 状态码	中文维基百科条目