HTTP 状态码由三位数字组成,第一位定义了响应的类别,后两位提供具体语义。
| 分类 | 含义 | 核心作用 |
|---|---|---|
| 1xx | 信息响应 | 请求已被接收,需要客户端继续执行或等待最终响应。通常是临时的。 |
| 2xx | 成功 | 客户端的请求已被成功接收、理解并接受。 |
| 3xx | 重定向 | 客户端需要采取进一步的动作才能完成请求。通常涉及 Location 头。 |
| 4xx | 客户端错误 | 请求本身存在问题(语法、权限、资源不存在等)。服务器已识别错误,请求不会成功。 |
| 5xx | 服务器错误 | 服务器在处理一个看似有效的请求时发生了内部错误,或者无法满足请求。 |
| 状态码 | 原因短语 | 说明 |
|---|---|---|
| 100 | Continue | 服务器已收到请求头,客户端应继续发送请求体。常用于大文件上传前的确认。 |
| 101 | Switching Protocols | 服务器同意切换协议(如从 HTTP 升级到 WebSocket)。 |
| 102 | Processing | (WebDAV)服务器已收到并正在处理请求,但无响应可用。 |
| 103 | Early Hints | 允许浏览器在服务器准备完整响应前,预先加载关键资源(如 CSS、JS),提升页面加载速度。 |
| 状态码 | 原因短语 | 说明 |
|---|---|---|
| 200 | OK | 请求成功。GET/PUT 的典型响应。 |
| 201 | Created | 请求成功并创建了新资源。POST 或某些 PUT 请求后的标准响应。 |
| 202 | Accepted | 请求已接受但尚未处理,适用于异步任务(如批量导入)。 |
| 203 | Non-Authoritative Information | 返回的元信息来自第三方缓存或代理,而非源服务器。 |
| 204 | No Content | 请求成功,但无内容返回。常用于删除操作或保存后无需刷新的场景。 |
| 205 | Reset Content | 请求成功,要求客户端重置表单视图(如清空所有输入字段)。 |
| 206 | Partial Content | 成功处理了范围请求(Range header),用于断点续传或分块下载。 |
| 207 | Multi-Status | (WebDAV)提供多个独立操作的结果(XML/JSON 体)。 |
| 208 | Already Reported | (WebDAV)DAV 绑定的成员已在前面部分列出,避免重复枚举。 |
| 226 | IM Used | 服务器已对资源应用了增量编码(Delta Encoding),响应是该资源的差异版本。 |
| 状态码 | 原因短语 | 说明 |
|---|---|---|
| 300 | Multiple Choices | 请求有多个可用响应,用户应选择一个。例如不同格式的视频文件列表。 |
| 301 | Moved Permanently | 资源已被永久移动到 Location 头指定的新 URL。搜索引擎会替换旧链接。 |
| 302 | Found | 资源临时移动到另一个 URL。搜索引擎通常保留旧链接。注意:浏览器实现常将 POST 改为 GET,推荐在现代 API 中使用 307/303。 |
| 303 | See Other | 响应可在另一个 URL(Location 头)通过 GET 方法获取。常用于 POST 后重定向到结果页。 |
| 304 | Not Modified | 条件请求(If-Modified-Since 等)时,资源未修改,客户端可使用缓存副本。仅应返回头和状态码,无内容体。 |
| 305 | Use Proxy | (已废弃)必须通过 Location 指定的代理访问资源。 |
| 307 | Temporary Redirect | 请求应临时重定向到新 URL。方法和请求体不得更改(与 302 不同)。标准临时重定向。 |
| 308 | Permanent Redirect | 请求应永久重定向到新 URL。方法和请求体不得更改(与 301 不同)。标准永久重定向。 |
| 状态码 | 原因短语 | 说明 |
|---|---|---|
| 400 | Bad Request | 服务器无法理解请求,通常是语法错误、无效请求消息帧或欺骗性路由。 |
| 401 | Unauthorized | 需要身份验证。响应必须包含 WWW-Authenticate 头来指导客户端如何认证。“未认证” |
| 402 | Payment Required | 预留状态码,用于未来数字支付系统。极少使用。 |
| 403 | Forbidden | 服务器理解请求但拒绝授权。认证凭据无效或用户无权限。“无权限” |
| 404 | Not Found | 服务器找不到请求的资源。也可能是出于安全考虑故意隐藏存在性。 |
| 405 | Method Not Allowed | 请求方法(GET/POST 等)在此资源上被禁用。响应应包含 Allow 头列出可用方法。 |
| 406 | Not Acceptable | 服务器无法生成匹配客户端 Accept 头指定内容协商类型的响应。 |
| 407 | Proxy Authentication Required | 必须通过代理认证。类似 401,响应需带 Proxy-Authenticate。 |
| 408 | Request Timeout | 服务器等待请求超时。"空闲连接超时"的常见表现。 |
| 409 | Conflict | 请求与资源当前状态冲突,如并发编辑冲突。 |
| 410 | Gone | 资源已永久删除,且无转发地址。搜索引擎会从索引中移除。 |
| 411 | Length Required | 服务器要求 Content-Length 请求头,但未提供。 |
| 412 | Precondition Failed | 条件请求(If-Match、If-Unmodified-Since 等)的某个前提条件为假。 |
| 413 | Payload Too Large | 请求体超过服务器允许的大小限制。 |
| 414 | URI Too Long | 请求的 URI(通常包含过多查询字符串)超过服务器能处理的长度。 |
| 415 | Unsupported Media Type | 请求实体的媒体格式不被资源接受。例如上传 JSON 到只接受 XML 的接口。 |
| 416 | Range Not Satisfiable | Range 头指定的范围无效或超出文件边界。 |
| 417 | Expectation Failed | 无法满足 Expect 请求头的要求(如 Expect: 100-continue)。 |
| 418 | I'm a teapot | 愚人节笑话(RFC 2324),服务器拒绝用茶壶煮咖啡。"超文本咖啡壶控制协议" |
| 421 | Misdirected Request | 请求发到了无法生成响应的服务器(在 HTTP/2 连接复用中)。 |
| 422 | Unprocessable Entity | (WebDAV / API 常用)请求格式正确,但语义错误(如必填字段缺失或校验失败)。 |
| 423 | Locked | (WebDAV)资源被锁定。 |
| 424 | Failed Dependency | 请求失败,因为依赖的另一个请求也失败了(如顺序操作中的前一步)。 |
| 425 | Too Early | 服务器拒绝处理可能被重放的请求,主要与 TLS 1.3 0-RTT 相关。 |
| 426 | Upgrade Required | 服务器要求客户端使用更高版本的协议(如升级到 HTTPS/WebSocket)。响应带 Upgrade 头。 |
| 428 | Precondition Required | 服务器要求请求必须是条件性的,以防止“丢失更新”冲突。 |
| 429 | Too Many Requests | 客户端在给定时间段内发送了过多请求(速率限制/API 限流)。Retry-After 头可提示等待时间。 |
| 431 | Request Header Fields Too Large | 请求头或某个头字段过大,服务器拒绝处理。 |
| 451 | Unavailable For Legal Reasons | 因法律原因(政府审查、版权投诉等)无法显示资源。向《华氏451度》致敬。 |
| 状态码 | 原因短语 | 说明 |
|---|---|---|
| 500 | Internal Server Error | 服务器遇到意外错误,无法完成请求。最通用的服务器错误码。 |
| 501 | Not Implemented | 服务器不支持完成请求所需的功能(例如未实现某个 HTTP 方法)。 |
| 502 | Bad Gateway | 服务器作为网关或代理时,从上游服务器收到无效响应。 |
| 503 | Service Unavailable | 服务器暂时无法处理请求(因过载或维护)。可带 Retry-After 头。 |
| 504 | Gateway Timeout | 服务器作为网关或代理时,未从上游服务器及时收到响应。 |
| 505 | HTTP Version Not Supported | 服务器不支持请求使用的 HTTP 协议版本。 |
| 506 | Variant Also Negotiates | 内容协商配置错误,导致透明协商产生循环引用。 |
| 507 | Insufficient Storage | (WebDAV)服务器存储空间不足,无法完成请求。 |
| 508 | Loop Detected | (WebDAV)服务器在请求处理过程中检测到无限循环。 |
| 510 | Not Extended | 请求需要进一步的扩展,才能在服务器上执行。 |
| 511 | Network Authentication Required | 客户端需要认证才能获得网络访问权限(例如机场 WiFi 强制门户)。 |
这类状态码是临时的,客户端通常不需要直接处理,由 HTTP 库自动完成。
Expect: 100-continue 头的请求,询问服务器是否愿意接收。服务器返回 100 Continue 表示可以继续发送请求体,拒绝则返回 417 Expectation Failed。POST /upload + Expect: 100-continue → 服务器 → 100 Continue → 客户端发送整个请求体。curl 等工具在发送特定大小的请求时会自动启用此机制。Upgrade 请求切换协议。这是建立 WebSocket 连接的标准状态码。GET /chat + Connection: Upgrade + Upgrade: websocket → 服务器 → 101 Switching Protocols,随后 TCP 连接转为 WebSocket 协议。Sec-WebSocket-Accept 用于握手验证。Link 头,预加载 CSS、JS 或关键子资源)。浏览器可以预先发起连接或预加载资源,从而明显提升页面加载速度。Link,例如 Link: </style.css>; rel=preload; as=style。GET、HEAD、POST(包含结果)、PUT(更新后的资源或结果)都很常用。POST,如果创建了新资源,更精准的做法是返回 201 Created。Location 中返回,响应体可包含新资源的表述。POST 新建用户、上传文件后,立即通过 Location 提供新资源的链接。POST /users → 201 Created + Location: /users/123 + { "id": 123, "name": "Alice" }。202 Accepted 和一个轮询结果的端点。客户端不应假设操作最终必定成功,需轮询状态。PUT 更新资源后无需返回任何数据;DELETE 成功删除后;为 SPA 保存数据但不刷新页面。204 的响应中不能有消息体,如果有,某些客户端会将其误认为是后续的新请求。Range 头的 GET 请求,返回了资源的一部分。主要用于断点续传、分片下载、视频拖动播放。Content-Range 指明本次返回的数据范围(如 bytes 0-499/1234),Content-Type 可能是 multipart/byteranges。Range: bytes=50000000-,服务器返回 206 和后续数据。POST /batch 一次性执行多个创建、更新、删除操作,每个操作独立返回状态。Accept 头)自动完成。Location 头给出的新 URL。搜索引擎会使用新 URL 替换旧 URL,浏览器也可能缓存这个重定向。301 时总会将 POST 转为 GET。若需保持方法不变,请使用 308 Permanent Redirect。POST 请求强制改为 GET,清空请求体。POST 方法的临时重定向场景中使用 302,而应使用 307 Temporary Redirect。GET 方法去请求 Location 头中的 URL,不论原始请求是什么方法。这完美解决了 POST 后刷新导致的重复提交问题。POST /cart/checkout → 303 See Other 重定向到 GET /order/confirmation/123,用户就能安全刷新确认页面。If-None-Match(ETag)或 If-Modified-Since 头的条件 GET 请求时,如果资源未发生改变,服务器便返回 304,通知客户端使用本地缓存的版本。304 响应绝不能包含消息体,只返回必要的头信息。POST 请求仍然发送 POST)。POST 重定向为 POST。POST 端点,应使用 308。WWW-Authenticate,指明服务器接受的认证方式(如 Bearer、Basic realm="xxx")。浏览器遇到 401 会弹出登录框。GET 的接口收到了 POST)。Allow 响应头,列出该资源支持的方法列表,如 Allow: GET, HEAD, OPTIONS。Accept、Accept-Language 等头中指定的要求的响应。例如,只返回 JSON 的 API 收到 Accept: text/html。Proxy-Authenticate 头。If-Match 和 ETag)更新资源时,因为资源已被他人修改而导致版本冲突。也用于重复创建唯一性资源等场景。Content-Length 头,但客户端没有发送。If-Match、If-Unmodified-Since)求值为“假”。常与状态码 409 配合,用于实现可靠的并发控制。client_max_body_size 控制)。服务器可能不处理该请求。Content-Type 格式不被资源所接受。例如,一个只接受 application/json 的接口收到了 text/xml。Range 指定的范围无效,超出了文件当前长度。响应头 Content-Range 可指出文件的实际有效范围。Expect 请求头的要求,通常发生在服务器拒绝处理 Expect: 100-continue 时。Upgrade 头会指示需要何种协议。If-Match 等头。Retry-After 头(单位秒或 HTTP 日期)告诉客户端等待多久后可重试。还可能看到 X-RateLimit-Limit、X-RateLimit-Remaining 等非标准但通用的限流头。Link 头指向一份阐述法律限制的页面。PATCH,但服务器没有实现它,或者请求要求某个特定的传输编码。Retry-After 头,告诉客户端大概多久后恢复,这对 SEO 和用户体验都至关重要。1xx 所有状态码(如 100 Continue)、204 No Content、304 Not Modified。若包含,可能被误认为下一个响应的开始并造成解析错乱。4xx, 5xx),强建议在消息体中提供对开发者友好的错误信息(如 JSON 格式的 { "error": "Invalid email", "field": "email" })。400;格式正确但内容语义错误(字段校验失败)用 422。429 的 Retry-After 头;对 503 设置的重试时间也要遵守,否则可能被惩罚。