HTTP 状态码

HTTP 状态码概述

HTTP状态码是服务器对客户端请求的三位数字代码响应，用于表示请求的处理结果。它位于响应的起始行（状态行）中。

状态码分类（首位数字）：

• 1xx (信息)：请求已接收，继续处理。
• 2xx (成功)：请求已成功被服务器接收、理解并处理。
• 3xx (重定向)：需要客户端进一步操作以完成请求。
• 4xx (客户端错误)：客户端请求有语法错误或无法被服务器理解/满足。
• 5xx (服务器错误)：服务器在处理请求时发生了内部错误。

一、 信息响应 (1xx)

表示临时响应，客户端应等待服务器的最终响应。在实际开发中，浏览器/客户端通常自动处理，无需前端开发者特别关注。

• 100 Continue：客户端应继续发送请求体（通常在发送了大文件前，先发Expect头询问服务器是否接受）。
• 101 Switching Protocols：服务器应客户端请求，切换协议（如切换到WebSocket）。
• 102 Processing：服务器已收到并正在处理请求，但尚无响应可用（用于防止客户端超时）。
• 103 Early Hints：在最终响应之前，先返回一些可能用到的资源提示（如预加载链接）。

二、 成功响应 (2xx)

表示请求成功处理。

• 200 OK：标准成功响应。GET请求返回资源，POST请求返回操作结果。
• 201 Created：创建成功。通常在POST或PUT请求后，新资源已被创建。响应头 Location 应包含新资源的URI。
• 202 Accepted：请求已接受，但尚未处理完成（异步任务，例如后台处理）。
• 204 No Content：服务器成功处理请求，但不返回任何内容（例如：DELETE请求成功，或表单提交后无需跳转）。
• 206 Partial Content：部分内容。客户端进行了范围请求（Range 头），服务器成功返回了指定范围的数据（用于断点续传、视频流）。

三、 重定向 (3xx)

表示需要客户端进行额外的操作（通常是向另一个URI重新发起请求）以完成请求。

• 301 Moved Permanently：永久重定向。请求的资源已被永久移动到新的URI。浏览器/搜索引擎会更新书签和索引。
• 302 Found：临时重定向。请求的资源临时从另一个URI响应。浏览器不会缓存此重定向，下次仍访问原地址。语义上原请求方法应为GET（历史上曾用于POST，但不规范）。
• 303 See Other：对应当前请求的响应可以在另一个URI上找到，应使用GET方法获取。常用于POST成功后重定向到一个结果页面。
• 304 Not Modified：缓存相关。客户端发送条件请求（如 If-Modified-Since），服务器判断资源未修改，告诉客户端直接使用本地缓存。这不是重定向，而是“无需传输，用缓存的”。
• 307 Temporary Redirect： 临时重定向，与302类似，但严格要求客户端保持原请求方法不变（如POST重定向后仍必须是POST）。
• 308 Permanent Redirect：永久重定向，与301类似，但严格要求客户端保持原请求方法不变。

核心区别：

• 永久 vs 临时： 301/308 是永久的；302/303/307 是临时的。
• 方法是否改变： 301/302 在历史实践中可能导致方法改为GET（不规范）；303 明确改为GET；307/308 明确不改变原方法。

四、 客户端错误 (4xx)

表示客户端的请求有问题。

• 400 Bad Request：通用客户端错误。服务器因请求语法、格式或无效而无法理解。前端应检查请求参数、格式（如JSON）。
• 401 Unauthorized：未认证。请求需要用户身份验证，且认证失败或未提供。通常与 WWW-Authenticate 头一起返回，提示认证方式。
• 403 Forbidden：禁止访问。服务器理解请求，但拒绝执行。与401不同，身份验证无帮助（权限不足）。
• 404 Not Found：资源不存在。服务器无法找到请求的资源。也常用于隐藏403（避免暴露资源存在）。
• 405 Method Not Allowed：请求方法（GET， POST等）不被目标资源支持。响应头 Allow 会列出支持的方法。
• 408 Request Timeout：服务器等待请求超时。客户端可以稍后重试。
• 409 Conflict：请求与服务器的当前状态冲突（例如：更新资源时版本冲突、创建资源时唯一键冲突）。
• 413 Payload Too Large：请求体超过服务器能处理的大小限制。
• 414 URI Too Long：请求的URI过长（通常发生在带大量查询参数的GET请求）。
• 415 Unsupported Media Type：请求的媒体格式（Content-Type）不被服务器支持。
• 429 Too Many Requests：速率限制。客户端在给定时间内发送了太多请求（“请求过多”）。

五、 服务器错误 (5xx)

表示服务器处理请求时发生内部错误，责任在服务器端。

• 500 Internal Server Error：通用服务器错误。服务器遇到了未曾预料的状况，无法完成请求。
• 501 Not Implemented：服务器不支持完成请求所需的功能（例如：使用了服务器未实现的HTTP方法）。
• 502 Bad Gateway：作为网关或代理的服务器，从上游服务器收到了无效响应。
• 503 Service Unavailable：服务器暂时无法处理请求（通常由于过载或维护）。这是最应被优雅处理的5xx错误，通常可配合 Retry-After 头提示客户端稍后重试。
• 504 Gateway Timeout：作为网关或代理的服务器，未能及时从上游服务器收到响应。

速查表

状态码	类别	含义	常见场景
200	成功	请求成功	GET/POST 成功
201	成功	资源创建成功	POST/PUT 创建新资源
204	成功	无内容返回	DELETE 成功，或不需要响应的操作
301	重定向	永久重定向	网站搬家，旧链接跳转到新链接
302	重定向	临时重定向（早期可能改GET）	临时活动页跳转
304	重定向(缓存)	资源未修改	协商缓存生效
400	客户端错误	请求错误	请求参数格式错误
401	客户端错误	未认证/认证失败	未登录或Token失效
403	客户端错误	禁止访问	权限不足
404	客户端错误	资源未找到	请求了不存在的URL
429	客户端错误	请求过于频繁	API调用超过频率限制
500	服务器错误	服务器内部错误	后端代码出现未捕获异常
502	服务器错误	网关错误	Nginx/Apache 无法从后端服务收到响应
503	服务器错误	服务不可用	服务器过载或正在维护
504	服务器错误	网关超时	后端服务响应超时