> For the complete documentation index, see [llms.txt](https://lizh.gitbook.io/knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lizh.gitbook.io/knowledge/frontend-xi-lie/09-ru-he-li-jie-http-xiang-ying-de-zhuang-tai-ma.md). # 如何理解HTTP响应的状态码 HTTP 响应状态码用来标识 HTTP 请求的处理结果，原始定义出自 `RFC 2616` 文档，后续在 `RFC 7231` 做了更新补充。 状态码一共分为五大类别： * 1xx：信息，临时响应，需要客户端继续操作 * 2xx：成功，请求已被服务器正常接收、处理 * 3xx：重定向，完成请求还需要后续额外操作 * 4xx：客户端错误，请求存在问题，服务器无法处理 * 5xx：服务器错误，服务器处理请求时发生异常 ![HTTP 状态码](https://my-files-1259410276.cos.ap-chengdu.myqcloud.com/md_images/http-status-code.png) **一般故障排除提示**： * 使用浏览器调试 Web 服务时，修改服务器配置之后务必刷新浏览器，避免读取旧缓存。 * 查阅服务器日志排查问题，Nginx、Apache 等 Web 服务器会生成 `access.log`（访问日志）和 `error.log`（错误日志），可以从中定位请求完整处理细节。 * HTTP 状态码属于标准定义，但**实际返回状态码由服务端软件实现决定**，不同服务框架返回的实际码值会存在差异，文档仅作为排查方向参考。 ## 1xx 信息（临时响应） 1xx 属于临时响应，代表请求已经被接收，但还需要继续处理；响应只包含状态行和可选响应头，以空行结束。HTTP/1.0 没有定义 1xx 状态码，除非试验场景，服务器不能对 HTTP/1.0 客户端返回 1xx。 **100 Continue（继续）** 服务器已经收到请求头，通知客户端可以继续发送请求体（POST 这类带 body 的请求）；如果请求已经完成，客户端直接忽略该响应。 使用前提：客户端请求头携带 `Expect: 100-continue`，发送请求体之前等待 100 响应。 **101 Switching Protocols（切换协议）** 响应客户端的 `Upgrade` 请求头，告知客户端服务器即将切换到新协议。典型场景：HTTP 升级为 WebSocket。 **102 Processing（WebDAV；RFC 2518）** WebDAV 场景使用。服务器已经接收到请求，正在进行处理，暂时没有可用的完整响应，防止客户端判定请求超时断开连接。 **103 Early Hints** 配合 `Link` 响应头使用，服务器还在准备正式响应的时候，允许浏览器提前预加载页面静态资源。 ## 2xx 成功 2xx 代表请求已经被服务器接收、解析、处理完毕。 **200 OK（成功）** 请求处理成功，响应正文根据请求方法含义不同： * `GET`：资源已经获取，正文返回资源数据 * `HEAD`：只返回响应头，没有响应正文 * `POST`：返回本次动作执行后的结果资源 * `TRACE`：正文返回服务器收到的原始请求报文 **201 Created（已创建）** 请求执行成功，服务器创建了新资源。多用于 POST、部分 PUT 新增资源场景，响应一般携带新资源的 Location 地址。 **202 Accepted（已接受）** 服务器已经收下请求，但还没有完成处理，属于异步处理。无法同步返回执行结果，需要其他后续流程处理任务，资源也不一定能最终创建成功。 **203 Non-Authoritative Information（非权威信息，HTTP/1.1）** 服务器处理请求成功，但返回的元信息不是源服务器原始数据，来自本地缓存、第三方副本；不是强制返回，仅在不返回 200 的场景才使用。 **204 No Content（无内容）** 服务器成功处理请求，**没有响应正文**。客户端可以拿响应头更新本地缓存。 **205 Reset Content（重置内容）** 服务器处理成功，无响应正文；通知客户端重置当前页面文档视图。典型场景：表单提交完成，清空表单输入，让用户重新输入。禁止携带响应体。 **206 Partial Content（部分内容）** 针对带 `Range` 请求头的分片请求，服务器返回资源的一部分。用于断点续传、大文件分片下载、视频流式加载。如果设置了条件校验，会配合 `If-Range` 头一起使用。 **207 Multi-Status（多状态，WebDAV；RFC 2518）** 响应体内返回 XML，一个请求对应多个子资源操作，每个子请求各自返回独立状态码。 **208 Already Reported（已报告，WebDAV；RFC 5842）** DAV 协议中，避免重复枚举同一个集合下多个绑定的内部成员。 **226 IM Used（RFC 3229）** 服务器完成 GET 请求，响应表示对资源实例执行增量操作后的结果。 ## 3xx 重定向 3xx 表示想要完成请求，还需要执行额外操作，绝大多数场景用于重定向。 浏览器遇到重定向，只有后续请求方法为 GET、HEAD 时，才可以自动跳转；客户端必须检测无限重定向循环，HTTP 规范建议浏览器自动跳转不超过 5 次。 **300 Multiple Choices（多种选择）** 请求资源存在多个可选响应，客户端、用户从中选择一个。响应可以在 Location 给出服务器优选地址，该响应允许被缓存。 **301 Moved Permanently（永久移动）** 资源永久迁移到新 URI，响应头 `Location` 给出新地址。GET、HEAD 请求浏览器会自动跳转；非 GET、HEAD 请求浏览器不能自动跳转，需要用户确认。响应默认可缓存。 历史兼容坑：部分旧浏览器 POST 收到 301 后，跳转请求会错误转为 GET。 **302 Found（临时移动）** 资源临时变更 URI，未来地址还可能发生变化，后续请求依旧使用原地址。仅当 `Cache-Control`、`Expires` 头指定才会被缓存。非 GET、HEAD 请求不能自动跳转。 历史兼容坑：很多旧浏览器把 302 按照 303 逻辑处理，POST 跳转后变成 GET 请求。 **303 See Other（查看其他位置）** 请求处理结果在另一个 URI，客户端**必须使用 GET 方法访问新地址**。多用于 POST 提交表单之后跳转页面。303 响应禁止缓存，跳转之后的请求可以被缓存。 **注意**：HTTP/1.1 之前不少浏览器无法正确理解 303。需要兼容这些旧浏览器时，用 302 更稳妥——它们处理 302 的方式，接近规范要求的 303 行为。 **304 Not Modified（未修改）** 缓存协商专用状态码。对比 `If-Modified-Since`、`If-None-Match`，客户端本地缓存资源没有过期，服务器不返回资源正文，直接复用浏览器本地缓存。**禁止携带响应体**。 **305 Use Proxy（使用代理）** 请求资源必须通过响应 `Location` 指定的代理访问。出于安全问题，该状态码已经被废弃。 **306（已废弃不再使用）** 早期 HTTP/1.1 草案定义，现在保留占位，实际不使用。 **307 Temporary Redirect（临时重定向）** 资源临时迁移，后续请求继续使用原地址；只有缓存头指定才允许缓存。和 302 区别：**跳转严格沿用原来的 HTTP 请求方法，POST 请求跳转依旧发 POST，不会改成 GET**。 **308 Permanent Redirect（永久重定向）** 资源永久迁移至 `Location` 指定 URI。和 301 区别：**跳转严格沿用原始请求方法，POST 跳转依旧发送 POST 请求**。 ## 4xx 客户端错误 4xx 代表客户端请求存在错误，服务器无法正常处理。除 HEAD 请求外，服务器应当返回实体说明错误原因。 如果客户端还在继续发送数据，服务端 TCP 栈需要做好处理，避免缓冲区残留数据干扰业务逻辑。 **400 Bad Request（错误请求）** 客户端请求存在问题，服务器解析失败。 常见原因： * 请求语法错误 * JSON、表单参数格式错误 * 请求头畸形 * Cookie 损坏 * 人为构造的错误 HTTP 请求 **401 Unauthorized（未授权）** 语义实际代表**未认证**，不是未授权。需要客户端完成身份认证；响应携带 `WWW-Authenticate` 质询头。如果已经带上身份凭证还返回 401，说明凭证校验失败。 **402 Payment Required（要求付费）** 保留预留状态码，最初设想用于数字支付系统，目前没有通用标准；部分开放 API 用于调用额度超限提示。 **403 Forbidden（禁止访问）** 服务器理解请求，但是拒绝执行。服务器知道客户端是谁，**身份认证也无法解决该错误，不要重复提交请求**。服务器可以返回实体说明拒绝理由，也可以伪装成 404，隐藏资源是否存在。 常见场景：权限不足、IP 被拒绝、站点要求 HTTPS、客户端证书缺失或不被信任、证书过期或已吊销。 **404 Not Found（未找到）** 服务器找不到请求对应的资源。URL 拼写错误、资源已经删除、接口端点存在但是数据不存在都可以返回 404；服务器也可以用 404 代替 403，隐藏资源权限信息。 排查时可依次确认： * URL 是否写错 * 资源是否已移动或删除 * 站点文档根目录配置是否正确 * Web 进程用户是否有目录读、执行权限 * 若目标是符号链接，服务器是否允许跟随 **405 Method Not Allowed（方法禁用）** 请求使用的 HTTP 方法，目标资源不支持。响应必须返回 `Allow` 头，列出该资源允许的 HTTP 方法。常见：接口只接受 POST，客户端发起 DELETE 请求。 **406 Not Acceptable（不接受）** 服务端内容协商之后，没有产出符合客户端 `Accept` 系列请求头要求的资源格式。可以返回实体列出可用资源选项。HEAD 请求禁止返回实体。 **407 Proxy Authentication Required（需要代理授权）** 和 401 类似，区别是身份认证需要在代理服务器完成，响应携带 `Proxy-Authenticate` 质询头。 **408 Request Timeout（请求超时）** 服务器等待客户端完整请求超时。服务器主动关闭空闲连接；浏览器预连接机制场景容易见到该状态码。部分服务器直接关闭 TCP 连接，不返回 408 报文。 **409 Conflict（冲突）** 请求和服务器当前资源状态产生冲突。典型场景：并发编辑同一份资源产生冲突。该状态适用于用户可以手动解决冲突，重新提交请求的业务。 **410 Gone（已删除）** 请求资源已经永久移除，没有转发地址。客户端应该删除本地缓存、删除指向该地址的链接。如果不能确定是否永久删除，使用 404。响应可以被缓存。 **411 Length Required（需要有效长度）** 服务器要求请求必须携带 `Content-Length` 请求头，但是客户端没有提供。补充正确 `Content-Length` 后可以重发请求。 **412 Precondition Failed（前提条件失败）** 请求头携带的预校验条件（`If-Match`、`If-Unmodified-Since` 等）服务器校验不通过。用于防止更新丢失。 **413 Payload Too Large（请求实体过大）** 请求提交的请求体大小超过服务器上限。服务器可以选择关闭连接，也可以返回 `Retry-After` 提示多久之后重试。 **414 URI Too Long（请求的 URI 过长）** 请求 URI 长度超出服务器解析上限。常见：GET 查询字符串拼接过多参数、重定向循环不断叠加 URL、利用超长 URL 做漏洞攻击。 **415 Unsupported Media Type（不支持的媒体类型）** 请求提交的请求体媒体类型，服务器不支持，拒绝处理该请求。 **416 Range Not Satisfiable（请求范围不符合要求，RFC 7233）** 请求头 `Range` 指定的分片范围全部超出资源实际大小，同时没有带上 `If-Range`。 **417 Expectation Failed（未满足期望值）** 服务器无法处理 `Expect` 请求头声明的预期。 **418 I'm a teapot（我是一个茶壶，RFC 2324）** IETF 愚人节 RFC 定义的彩蛋状态码，现实业务服务器不需要实现；部分项目用作趣味彩蛋。 **420 Enhance Your Calm（保持冷静）** 非 RFC 标准。Twitter Search、Trends API 在客户端被限流时曾返回该码；现行通用限流多用 429。 **421 Misdirected Request（错误定向请求，RFC 7540）** 请求被发送给一台不能生成对应响应的服务器。 **422 Unprocessable Entity（无法处理的实体，WebDAV；RFC 4918）** 报文格式语法正确，但是业务语义校验错误，无法处理。比如 JSON 格式正确，但是字段业务规则校验失败。 **423 Locked（锁定，WebDAV；RFC 4918）** 访问的资源处于锁定状态。 **424 Failed Dependency（依赖失败，WebDAV；RFC 4918）** 本次请求的执行依赖上一个请求，上一个请求失败，导致本次请求失败。 **425 Too Early（太早了）** 服务器拒绝处理存在重放风险的过早请求，防止重放攻击。 **426 Upgrade Required（需要升级，RFC 2817）** 服务器拒绝当前协议处理请求；响应携带 `Upgrade` 头，告知客户端需要切换的协议版本。 **428 Precondition Required（需要前提条件，RFC 6585）** 源服务器要求请求必须是条件请求，用来防止更新丢失问题，避免客户端覆盖别人已经修改过的数据。 **429 Too Many Requests（请求过多，RFC 6585）** 限流，客户端短时间发送大量请求。可以返回 `Retry-After` 告知冷却时间。 **431 Request Header Fields Too Large（请求头过大，RFC 6585）** HTTP 请求头整体大小超过服务器上限；缩小请求头之后可以重发请求。 **451 Unavailable For Legal Reasons（由于法律原因无法使用）** 资源因为法律审查、合规原因无法访问。 **444** Nginx 扩展，服务器直接关闭连接，不返回任何响应内容。 **450** Windows 家长控制系统拦截，非标准 RFC 状态码。 ## 5xx 服务器错误 5xx 代表服务器内部处理发生异常；HEAD 之外的请求，服务器返回实体描述错误情况；状态码适用于全部 HTTP 请求方法。 **500 Internal Server Error（内部服务器错误）** 通用服务器异常，服务器遇到未知错误，无法完成请求。常见：代码异常、配置文件语法错误、依赖缺失。 **501 Not Implemented（尚未实施）** 服务器不支持该 HTTP 请求方法。规范强制 GET、HEAD 必须支持，不会返回 501。 **502 Bad Gateway（错误网关）** 网关、反向代理拿到后端上游服务器返回的无效响应。排查方向：后端服务是否正常、代理配置、代理与后端网络连通性、端口、socket 权限。 **503 Service Unavailable（服务不可用）** 服务器临时无法处理请求，原因：服务器维护、CPU 与内存过载。属于临时状态，响应可以携带友好提示页面；建议带上 `Retry-After` 头告知恢复时间；该响应一般不应该被浏览器缓存。 **504 Gateway Timeout（网关超时）** 网关、反向代理等待后端上游服务器响应超时。排查：后端接口执行耗时、服务器之间网络、代理超时配置。 **505 HTTP Version Not Supported（HTTP 版本不受支持）** 服务器不支持请求报文使用的 HTTP 协议版本。 **506 Variant Also Negotiates（协商引起的异常，RFC 2295）** 服务器内部配置错误，透明内容协商产生循环引用。 **507 Insufficient Storage（存储不足，WebDAV；RFC 4918）** 服务器存储空间不足，无法完成该请求。属于临时状态。 **508 Loop Detected（循环检测，WebDAV；RFC 5842）** 处理请求的时候检测到无限循环。 **510 Not Extended（扩展不足，RFC 2774）** 服务器需要客户端开启扩展，才能完成本次请求。 **511 Network Authentication Required（网络身份验证要求，RFC 6585）** 客户端需要完成网络层面身份认证。典型场景：WiFi 门户网页，需要登录上网。 ## 参考链接 [MDN HTTP 响应代码](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status)