工具哇!

HTTP 状态码对照表

HTTP 状态码是服务器对客户端请求的响应状态的数字化标识,了解它们有助于快速定位网页、API 或网络请求中的问题

HTTP 状态码详解

HTTP 状态码由三位数字组成,第一位定义了响应的类别,后两位提供具体语义。

分类 含义 核心作用
1xx 信息响应 请求已被接收,需要客户端继续执行或等待最终响应。通常是临时的。
2xx 成功 客户端的请求已被成功接收、理解并接受。
3xx 重定向 客户端需要采取进一步的动作才能完成请求。通常涉及 Location 头。
4xx 客户端错误 请求本身存在问题(语法、权限、资源不存在等)。服务器已识别错误,请求不会成功。
5xx 服务器错误 服务器在处理一个看似有效的请求时发生了内部错误,或者无法满足请求。

完整 HTTP 状态码对照表

1xx:信息响应

状态码 原因短语 说明
100 Continue 服务器已收到请求头,客户端应继续发送请求体。常用于大文件上传前的确认。
101 Switching Protocols 服务器同意切换协议(如从 HTTP 升级到 WebSocket)。
102 Processing (WebDAV)服务器已收到并正在处理请求,但无响应可用。
103 Early Hints 允许浏览器在服务器准备完整响应前,预先加载关键资源(如 CSS、JS),提升页面加载速度。

2xx:成功

状态码 原因短语 说明
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),响应是该资源的差异版本。

3xx:重定向

状态码 原因短语 说明
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 不同)。标准永久重定向。

4xx:客户端错误

状态码 原因短语 说明
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-MatchIf-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度》致敬。

5xx:服务器错误

状态码 原因短语 说明
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 强制门户)。

常见状态码详解

1xx:信息响应(中间状态)

这类状态码是临时的,客户端通常不需要直接处理,由 HTTP 库自动完成。

100 Continue

  • 详细说明:客户端在发送大请求体(如文件上传)前,先发送包含 Expect: 100-continue 头的请求,询问服务器是否愿意接收。服务器返回 100 Continue 表示可以继续发送请求体,拒绝则返回 417 Expectation Failed
  • 典型流程:客户端 → POST /upload + Expect: 100-continue → 服务器 → 100 Continue → 客户端发送整个请求体。
  • 注意事项:如果服务器不返回 100,客户端应在一段超时后直接发送请求体(视实现而定)。curl 等工具在发送特定大小的请求时会自动启用此机制。

101 Switching Protocols

  • 详细说明:服务器同意按照客户端发起的 Upgrade 请求切换协议。这是建立 WebSocket 连接的标准状态码。
  • 典型流程:客户端 → GET /chat + Connection: Upgrade + Upgrade: websocket → 服务器 → 101 Switching Protocols,随后 TCP 连接转为 WebSocket 协议。
  • 相关头Sec-WebSocket-Accept 用于握手验证。

102 Processing (WebDAV)

  • 详细说明:服务器已收到请求并正在处理,但处理可能需要较长时间,通过发送 102 来防止客户端误以为超时并断开连接。可以多次发送 102,最终发送 2xx/4xx/5xx 最终响应。
  • 使用场景:批量文件操作、需要长时间计算的 API。

103 Early Hints (HTTP/2 & HTTP/3)

  • 详细说明:允许服务器在准备完整响应之前,先发送一些对渲染页面至关重要的头信息(如 Link 头,预加载 CSS、JS 或关键子资源)。浏览器可以预先发起连接或预加载资源,从而明显提升页面加载速度。
  • 相关头Link,例如 Link: </style.css>; rel=preload; as=style

2xx:成功(服务器正常完成请求)

200 OK

  • 详细说明:万能成功码。请求成功,响应体里包含所请求的数据。对 GETHEADPOST(包含结果)、PUT(更新后的资源或结果)都很常用。
  • 注意:对于 POST,如果创建了新资源,更精准的做法是返回 201 Created

201 Created

  • 详细说明:请求已成功,并且因此创建了一个或多个新资源。新资源的 URI 会在响应头 Location 中返回,响应体可包含新资源的表述。
  • 典型场景POST 新建用户、上传文件后,立即通过 Location 提供新资源的链接。
  • 示例POST /users201 Created + Location: /users/123 + { "id": 123, "name": "Alice" }

202 Accepted

  • 详细说明:请求已被接受排队,但尚未处理,处理结果不确定。适用于异步操作,如批量导入、发送邮件、启动后台任务等。响应体通常包含一个用于跟踪状态的 URL 或任务 ID。
  • 典型场景:提交一个大数据处理作业,服务器返回 202 Accepted 和一个轮询结果的端点。客户端不应假设操作最终必定成功,需轮询状态。

203 Non-Authoritative Information

  • 详细说明:请求成功,但返回的元信息(可能包含部分或全部响应)来自第三方缓存或代理,而不是源服务器。当代理修改过响应(如转换了内容编码)时,会将 200 转换成 203 以提醒客户端。

204 No Content

  • 详细说明:请求成功,但服务器没有需要返回的内容。这也是 2xx,不可返回响应体。浏览器接收到 204 时页面保持不变。
  • 典型场景PUT 更新资源后无需返回任何数据;DELETE 成功删除后;为 SPA 保存数据但不刷新页面。
  • 注意:严格来说,204 的响应中不能有消息体,如果有,某些客户端会将其误认为是后续的新请求。

205 Reset Content

  • 详细说明:类似于 204,但额外要求客户端重置文档视图。主要用于传统表单提交后,若用户刚刚提交了表单,浏览器可以清空所有字段。在现代 API 中几乎不用。

206 Partial Content

  • 详细说明:服务器成功处理了带 Range 头的 GET 请求,返回了资源的一部分。主要用于断点续传、分片下载、视频拖动播放。
  • 相关头Content-Range 指明本次返回的数据范围(如 bytes 0-499/1234),Content-Type 可能是 multipart/byteranges
  • 示例:下载一个 100MB 文件,暂停后可请求 Range: bytes=50000000-,服务器返回 206 和后续数据。

207 Multi-Status (WebDAV)

  • 详细说明:在一个响应中携带多个独立操作的状态信息。请求体是 XML/JSON,响应体也会详尽列出每个操作的结果(2xx, 4xx, 5xx 混合)。现代 RESTful API 批量操作也常用。
  • 典型场景POST /batch 一次性执行多个创建、更新、删除操作,每个操作独立返回状态。

208 Already Reported (WebDAV)

  • 详细说明:在 PROPFIND 的深度请求中,如果某个资源绑定了集合中已经列出的其他资源,为避免重复列举,该成员的状态将标记为 208。普通 API 开发极少用到。

226 IM Used

  • 详细说明:服务器支持增量编码(Delta Encoding),响应只返回了该资源相对于客户端已知版本的差异部分。客户端应用这些差异后即可获得完整表示,可大幅节省带宽。

3xx:重定向(需要客户端采取行动)

300 Multiple Choices

  • 详细说明:请求的资源有多个可用的表现形式(如视频的不同格式、文档的不同语言版),响应体里会列出这些选项,由客户端或用户选择一个。
  • 很少使用:现代开发更倾向于通过内容协商(Accept 头)自动完成。

301 Moved Permanently

  • 详细说明:请求的 URL 已永久性地移动到 Location 头给出的新 URL。搜索引擎会使用新 URL 替换旧 URL,浏览器也可能缓存这个重定向。
  • 历史问题:虽然原标准要求保持原方法和请求体,但很多客户端(如浏览器)在处理 301 时总会将 POST 转为 GET。若需保持方法不变,请使用 308 Permanent Redirect

302 Found (Historically: Moved Temporarily)

  • 详细说明:请求的 URL 临时存在于另一个地址。这是历史上导致最多混乱的状态码。绝大多数客户端实现都会在收到 302 时将 POST 请求强制改为 GET,清空请求体。
  • 最佳实践:永远不要在需要保持 POST 方法的临时重定向场景中使用 302,而应使用 307 Temporary Redirect

303 See Other

  • 详细说明:明确要求客户端使用 GET 方法去请求 Location 头中的 URL,不论原始请求是什么方法。这完美解决了 POST 后刷新导致的重复提交问题。
  • Post/Redirect/Get 模式POST /cart/checkout303 See Other 重定向到 GET /order/confirmation/123,用户就能安全刷新确认页面。

304 Not Modified

  • 详细说明:当客户端发出附带 If-None-Match(ETag)或 If-Modified-Since 头的条件 GET 请求时,如果资源未发生改变,服务器便返回 304,通知客户端使用本地缓存的版本。304 响应绝不能包含消息体,只返回必要的头信息。
  • 作用:大幅节省带宽和加载时间,是现代 Web 缓存策略的核心。

305 Use Proxy(已废弃)、306 Switch Proxy(已废弃)

  • 305 原意要求必须通过代理访问,但存在安全风险,已被现代浏览器废弃。

307 Temporary Redirect

  • 详细说明:临时重定向的标准选择。服务器保证下一个请求的方法和请求体必须保持原样,不会被改变。浏览器会向新 URL 重新发出原始请求(如 POST 请求仍然发送 POST)。
  • 场景:表单提交到某个临时维护的备用服务器,不希望方法被改变。

308 Permanent Redirect

  • 详细说明:永久重定向的标准选择。类似于 301,但和 307 一样强制保持原方法和请求体不变。浏览器会将 POST 重定向为 POST
  • 注意:由于 308 是较新的状态码,在旧版浏览器上支持可能有限,但现代浏览器均已支持。API 设计时,如需永久移走一个 POST 端点,应使用 308。

4xx:客户端错误(请求有问题)

400 Bad Request

  • 详细说明:服务器认为客户端发送的请求存在语法错误、无法被理解。如 JSON 格式错误、必填参数缺失、请求被恶意篡改等。
  • 使用建议:应在响应体中提供具体错误描述,帮助客户端调试。

401 Unauthorized

  • 详细说明:请求缺少有效的认证凭据,或提供的凭据已过期/无效。这不是指“权限不足”,而是指“没有认证”或“认证失败”
  • 必须包含:响应头必须包含 WWW-Authenticate,指明服务器接受的认证方式(如 BearerBasic realm="xxx")。浏览器遇到 401 会弹出登录框。

402 Payment Required

  • 预留状态:为了未来的数字支付或计费系统预留,目前极少正式使用。有时被 API 用作“额度已用完”的专用返回,但这并非标准。

403 Forbidden

  • 详细说明:服务器成功认证了客户端的身份,但该客户端没有访问所请求资源的权限(授权失败)。与 401 的核心区别在于“已经知道你是谁,但你不能这么做”
  • 安全考量:有时为了避免攻击者侦查到资源存在,服务器会用 404 来代替 403。

404 Not Found

  • 详细说明:服务器找不到请求的 URI,或不希望透露该资源当前是否存在。
  • 使用建议:对于 GET 请求,资源永久不存在可以更精确地用 410;但 404 更通用。对于 API,务必清楚区分“路径不存在”和“资源 ID 不存在”。

405 Method Not Allowed

  • 详细说明:资源存在,但用于请求它的 HTTP 方法不被支持(如只允许 GET 的接口收到了 POST)。
  • 必须包含Allow 响应头,列出该资源支持的方法列表,如 Allow: GET, HEAD, OPTIONS

406 Not Acceptable

  • 详细说明:服务器无法生成任何匹配客户端 AcceptAccept-Language 等头中指定的要求的响应。例如,只返回 JSON 的 API 收到 Accept: text/html

407 Proxy Authentication Required

  • 详细说明:与 401 类似,但表示客户端必须先向代理服务器进行认证。响应需带 Proxy-Authenticate 头。

408 Request Timeout

  • 详细说明:服务器等待客户端发送完整请求的时间过长,主动关闭了空闲连接。客户端看到此错误时可以重新发起连接并重试请求(只要不是幂等操作需谨慎)。

409 Conflict

  • 详细说明:请求与服务器资源的当前状态发生冲突。最经典的场景是通过乐观锁(If-Match 和 ETag)更新资源时,因为资源已被他人修改而导致版本冲突。也用于重复创建唯一性资源等场景。
  • API 设计:返回 409 时,通常应携带当前服务器端的资源状态或冲突详情。

410 Gone

  • 详细说明:资源曾经存在,但已被永久性地删除,且没有留下重定向地址。搜索引擎会立即从索引中移除该链接。如果资源未来可能恢复,仍应使用 404。

411 Length Required

  • 详细说明:服务器坚持要求请求中包含有效的 Content-Length 头,但客户端没有发送。
  • 场景:防止分块编码发送未知大小的请求体。

412 Precondition Failed

  • 详细说明:请求中携带的一个或多个条件头(如 If-MatchIf-Unmodified-Since)求值为“假”。常与状态码 409 配合,用于实现可靠的并发控制。

413 Payload Too Large

  • 详细说明:请求体的大小超过了服务器允许的最大限制(在 Nginx 中常由 client_max_body_size 控制)。服务器可能不处理该请求。

414 URI Too Long

  • 详细说明:请求的 URI(包括路径和查询字符串)长度超过了服务器能处理的范围。常发生在 GET 请求传递了过长的查询参数时。

415 Unsupported Media Type

  • 详细说明:请求体的 Content-Type 格式不被资源所接受。例如,一个只接受 application/json 的接口收到了 text/xml

416 Range Not Satisfiable

  • 详细说明:请求头中 Range 指定的范围无效,超出了文件当前长度。响应头 Content-Range 可指出文件的实际有效范围。

417 Expectation Failed

  • 详细说明:无法满足 Expect 请求头的要求,通常发生在服务器拒绝处理 Expect: 100-continue 时。

418 I'm a teapot

  • 愚人节笑话:源自 1998 年的一个恶搞 RFC,表示服务器是一台茶壶,拒绝煮咖啡。被许多框架(如 Flask、Express)引入作为彩蛋。

421 Misdirected Request

  • 详细说明:在 HTTP/2 中,请求被发到了同一个 IP 上但并非为该域名服务的服务器,可能是因为连接重用和 TLS 证书不匹配等问题。

422 Unprocessable Entity (WebDAV / API 必知)

  • 详细说明:请求格式完全正确,但语义层面存在错误,导致服务器无法处理。这是现代 API 中用于“数据校验失败”的标准状态码,比 400 更精确。
  • 典型场景:必填字段缺失、邮箱格式错误、数值超出业务范围等。响应体应详细列出校验失败的具体字段和原因。

423 Locked (WebDAV)

  • 详细说明:目标资源已被锁定。例如,某用户正在编辑文档时设置了锁,其他用户尝试修改便会收到 423。

424 Failed Dependency (WebDAV)

  • 详细说明:当前请求的失败是源于之前一个请求的失败。例如,在执行一组顺序操作时,若上一步失败,后续步骤无法执行。

425 Too Early

  • 详细说明:与 TLS 1.3 的 0-RTT 特性相关。服务器拒绝一个可能被重放攻击的请求,提示客户端等待安全握手完成后再试。

426 Upgrade Required

  • 详细说明:服务器要求客户端使用升级后的协议(如从 HTTP 升级到 HTTPS)。Upgrade 头会指示需要何种协议。

428 Precondition Required

  • 详细说明:服务器要求该请求必须是条件性的。它能有效防止“丢失更新”问题:要求客户端在修改前必须先带上 If-Match 等头。

429 Too Many Requests

  • 详细说明:客户端在给定的时间内发送了太多请求,触发了服务器的限流策略(Rate Limiting)。
  • 关键响应头:通常会带上 Retry-After 头(单位秒或 HTTP 日期)告诉客户端等待多久后可重试。还可能看到 X-RateLimit-LimitX-RateLimit-Remaining 等非标准但通用的限流头。

431 Request Header Fields Too Large

  • 详细说明:请求头整体大小或某个单一头的值过大,超过了服务器的处理限制。

451 Unavailable For Legal Reasons

  • 详细说明:服务器因受到法律要求(法院判决、政府审查、版权投诉等)而无法提供资源。该代码是对小说《华氏 451 度》的致敬。
  • 常见响应:可能包含一个 Link 头指向一份阐述法律限制的页面。

5xx:服务器错误(服务器处理失败)

500 Internal Server Error

  • 详细说明:最通用的服务器错误,表示服务器遇到了意料之外的状况,无法明确归类。安全准则:永远不要将详细的错误堆栈或数据库查询暴露在 500 响应体中,以免泄漏内部信息。 日志记录在服务器端。

501 Not Implemented

  • 详细说明:服务器不支持完成该请求所需的功能。比如请求方法为 PATCH,但服务器没有实现它,或者请求要求某个特定的传输编码。

502 Bad Gateway

  • 详细说明:服务器作为网关或代理时,从上游服务器(如应用服务器、第三方 API)收到了一个无效的响应。对于使用 Nginx 反向代理的用户,这是最熟悉的错误之一,通常表示上游服务挂了或返回了烂数据。

503 Service Unavailable

  • 详细说明:服务器目前暂时无法处理请求(因为临时过载、停机维护等)。这是表示“临时状态”的服务器错误。
  • 最佳实践:强烈建议在 503 响应中加入 Retry-After 头,告诉客户端大概多久后恢复,这对 SEO 和用户体验都至关重要。

504 Gateway Timeout

  • 详细说明:网关或代理服务器在等待上游服务器的响应时超时。常见于数据库查询过慢、第三方服务调用超时,导致 Nginx 等代理超时放弃。

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)才能接入互联网。浏览器通常会检测到这个状态码并跳转到强制门户的登录页面。

补充科普与实践指南

状态码与消息体

  • 绝不能包含消息体1xx 所有状态码(如 100 Continue)、204 No Content304 Not Modified。若包含,可能被误认为下一个响应的开始并造成解析错乱。
  • 可以包含消息体,但可能为空:其他所有状态码,特别是错误状态码(4xx, 5xx),强建议在消息体中提供对开发者友好的错误信息(如 JSON 格式的 { "error": "Invalid email", "field": "email" })。

常见误用与最佳选择

  • 所有错误都返回 200 OK:这是最糟糕的做法,客户端必须解析响应体才能判断成败,彻底绕开了 HTTP 的语义层,破坏了缓存、重试等机制。
  • 401 vs 403 的混淆:牢记“401 是没带票或票无效(需登录)”;“403 是带了票但不让你进(已登录但无权)”。
  • 404 的欺骗性:有些服务器出于安全考虑,即使资源存在但用户无权限,也可能返回 404 而非 403,以隐藏资源存在性。
  • 正确使用 301/302 与 307/308:传统 301/302 会使某些客户端将 POST 重定向变为 GET(历史兼容性)。现代 API 若需保留请求方法和请求体,应使用 307(临时)和 308(永久)。
  • 模糊的 400 vs 422:请求格式错误(JSON 无法解析)用 400;格式正确但内容语义错误(字段校验失败)用 422
  • 自动化客户端(如搜索引擎爬虫)的处理:永远要尊重 429Retry-After 头;对 503 设置的重试时间也要遵守,否则可能被惩罚。

非标准但常见的状态码

  • 状态码是可扩展的:如果遇到不熟悉的状态码,根据第一位数字理解其类别即可。
  • Nginx 499: 客户端在服务器返回响应前主动关闭了连接。
  • Cloudflare 52x 系列: 如 520 未知错误、521 服务器未连接、522 连接超时、523 无法访问、524 超时、525 SSL 握手失败等,专用于 CDN 场景。
  • Spring Framework / Micrsoft: 存在一些内部使用的状态码,但不应在不理解的情况下直接暴露给外部客户端。