HTTP 状态码查询与接口排查参考

按状态码、英文短语、分类、来源、生命周期和排查关键词查询 HTTP 响应状态。这个页面覆盖常见 RFC 标准状态码、WebDAV 扩展码、CDN 与代理常见非标准状态码,适合排查 REST API、浏览器请求、SEO 抓取、重定向、认证失败、限流、网关错误和上游超时问题。

  • 支持按状态码、英文短语、分类、相关状态码、厂商来源和排查关键词搜索。
  • 可以快速对比 1xx、2xx、3xx、4xx、5xx 的语义边界。
  • 说明状态码在接口设计、浏览器调试、CDN 故障和服务端排障中的实际用法。

查询 HTTP 状态码

输入 404、Bad Gateway、redirect、timeout、Cloudflare、WebSocket、认证、缓存、限流等数字、短语或排查关键词。

1xx 信息性响应

最终响应之前的临时响应,通常由 HTTP 客户端、服务器、代理或浏览器网络层处理。

100

Continue

服务器已收到请求头,客户端可以继续发送请求体。

1xx 信息性响应 标准 不建议作为公共 API 契约 RFC 9110
详情

100 Continue 表示服务器已经收到请求的初始部分,通常是请求行、请求头以及必要的请求元信息,并且根据目前掌握的信息,暂时没有发现必须立即拒绝该请求的问题。它属于 1xx 信息性状态码,是请求处理过程中的临时响应,不代表请求已经成功完成。它的核心作用是告诉客户端:可以继续发送剩余的请求内容,尤其是较大的请求体。这个状态码最常见于 Expect: 100-continue 机制。客户端先发送请求头,服务端检查认证信息、权限、Content-Type、Content-Length、资源限制等前置条件;如果没有发现明显问题,就返回 100 Continue,客户端随后再发送请求体。最终请求是否成功,仍然以后续返回的最终状态码为准。换句话说,当用户搜索“HTTP 100 是什么意思”、“100 Continue 怎么解决”或“接口返回 100 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。信息性临时响应,重点是客户端不能把它当作最终结果。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 客户端需要上传大文件、大体积表单、批量 JSON 数据或其他较大的请求体,希望在正式发送内容前先确认服务器是否愿意接收。
  • 请求带有 Expect: 100-continue 请求头时,客户端可以先发送请求头,等待服务器返回 100 Continue 后再继续发送请求体。
  • 服务端希望在接收完整请求体之前,先根据请求头判断认证、权限、内容类型、内容长度、路由或资源限制是否明显不满足。
  • 代理服务器、反向代理、负载均衡或 API 网关参与请求转发时,需要正确处理客户端和源站之间的临时响应。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 100 Continue,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
排查建议
  • 客户端收到 100 Continue 后,应继续发送剩余的请求体,例如文件内容、表单数据、JSON 数据或其他请求负载。
  • 不要把 100 Continue 当作最终结果处理,客户端还必须继续等待服务器返回最终状态码。
  • 如果请求卡在 100 Continue 附近,应检查客户端是否真的在收到临时响应后继续发送请求体。
  • 如果服务端已经决定拒绝请求,应直接返回 401、403、413、415 或 417 等最终错误状态码。
  • 排查 100 Continue 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
不建议用于
  • 不要把 100 Continue 当作最终成功;它只是允许客户端继续发送请求体。
  • 不要在业务代码里手动返回 100,通常交给 HTTP 服务器或网关处理。
  • 不要在已经收到完整请求体后再返回 100,此时应该直接返回最终状态码。
来源: RFC 9110 相关状态码: 101, 102, 103, 200, 202, 204, 413, 417
101

Switching Protocols

服务器同意切换到客户端请求的协议。

1xx 信息性响应 标准 不建议作为公共 API 契约 RFC 9110
详情

101 Switching Protocols 表示服务器已经理解客户端通过 Upgrade 请求头提出的协议切换请求,并且同意把当前连接切换到另一个协议。它属于 1xx 信息性状态码,常见于协议升级握手阶段,不是普通业务接口用来返回数据的成功状态码。服务器返回 101 后,后续通信将按照响应中 Upgrade 头指定的新协议继续进行,而不再按原来的 HTTP 报文格式解析。最常见的场景是 WebSocket 握手。换句话说,当用户搜索“HTTP 101 是什么意思”、“101 Switching Protocols 怎么解决”或“接口返回 101 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。信息性临时响应,重点是客户端不能把它当作最终结果。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 客户端通过 Upgrade 请求头请求把当前 HTTP 连接升级为其他协议,并且服务器支持该协议切换。
  • WebSocket 建立连接时,客户端发送握手请求,服务器校验通过后返回 101 Switching Protocols。
  • 反向代理、负载均衡或 API 网关转发 WebSocket 请求时,需要正确保留 Upgrade 和 Connection 相关头部。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 101 Switching Protocols,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 101 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 客户端收到 101 后,应停止按照普通 HTTP 响应体解析后续数据,并切换为响应头中 Upgrade 指定的协议。
  • 如果 WebSocket 连接建立失败,应检查 Upgrade、Connection、Sec-WebSocket-Key 和 Sec-WebSocket-Version 等必要头部。
  • 如果经过 Nginx、CDN 或负载均衡后无法连接,应检查中间层是否允许长连接和协议升级。
  • 排查 101 Switching Protocols 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 101 当作普通 API 成功响应;它只适合真实的协议升级。
  • 不要在没有 Upgrade 请求头时返回 101。
  • 不要用 101 表示建议升级协议;这种情况更接近 426。
来源: RFC 9110 相关状态码: 100, 200, 204, 400, 426
102

Processing

服务器已收到完整请求,正在处理但尚未产生最终响应。

1xx 信息性响应 已废弃 不建议作为公共 API 契约 RFC 2518
详情

102 Processing 表示服务器已经收到完整请求,并且正在处理该请求,但目前还没有可以返回的最终响应。它最初来自 WebDAV,用于处理耗时较长的资源操作。它的作用是告诉客户端:请求没有丢失,服务器仍在工作,请继续等待最终结果。102 不是最终响应,也不表示请求成功;真正的处理结果仍以后续最终状态码为准。需要注意的是,102 最初在 RFC 2518 中定义,后来从 RFC 4918 的 WebDAV 规范中移除,因此现代普通 Web 服务很少主动返回它。换句话说,当用户搜索“HTTP 102 是什么意思”、“102 Processing 怎么解决”或“接口返回 102 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。信息性临时响应,重点是客户端不能把它当作最终结果。它来自 RFC 2518,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • WebDAV 请求需要较长时间处理时,服务器可以用 102 告诉客户端请求已经收到并正在执行。
  • 请求涉及多个文件、目录、资源集合或批量操作,服务端短时间内无法生成最终响应。
  • 客户端或中间代理可能因为长时间没有任何响应而断开连接时,服务器可以通过临时响应表示处理仍在继续。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 102 Processing,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 102 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 客户端收到 102 后,应继续等待最终响应,而不是把它当作请求成功或失败。
  • 如果请求长时间只收到 102,应检查服务端任务是否存在死锁、队列阻塞、后端超时或资源锁等待。
  • 如果业务接口需要表达任务已接收但稍后处理,通常应使用 202 Accepted,并返回任务 ID 或查询地址。
  • 排查 102 Processing 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 102 当作异步任务已创建;现代 API 更适合返回 202。
  • 不要把 102 当作最终成功,它只表示服务端还在处理。
  • 不要用 102 表示可以继续发送请求体;那是 100 的语义。
来源: RFC 2518 相关状态码: 100, 103, 200, 202, 207, 408, 409, 423, 504, 507
103

Early Hints

服务器提前发送可能用于最终响应的提示头。

1xx 信息性响应 标准 不建议作为公共 API 契约 RFC 8297
详情

103 Early Hints 表示服务器在最终响应还没有准备好之前,先发送一组可能会出现在最终响应中的响应头提示。它主要用于页面性能优化,而不是表示业务处理结果。最常见的用途是在服务器生成 HTML 页面、执行后端查询或等待上游响应时,提前把 Link 头发送给浏览器,让浏览器尽早预连接、预加载或预取关键资源,例如 CSS、JavaScript、字体、图片或第三方域名连接。103 不会替代最终响应,客户端仍然必须等待后续的最终状态码。换句话说,当用户搜索“HTTP 103 是什么意思”、“103 Early Hints 怎么解决”或“接口返回 103 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。信息性临时响应,重点是客户端不能把它当作最终结果。它来自 RFC 8297,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 服务器生成最终 HTML 响应需要一定时间,但已经知道页面大概率会依赖哪些关键资源。
  • 服务端希望通过 Link: rel=preload、rel=preconnect 或 rel=dns-prefetch 等响应头提前提示浏览器。
  • CDN、边缘节点或应用服务器能根据路由、缓存元数据或模板信息提前推断最终页面需要的资源。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 103 Early Hints,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 103 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 客户端收到 103 后,不应把它当作最终响应处理,而应继续等待后续的最终状态码和最终响应头。
  • 如果 103 没有效果,应检查 Link 头以及 rel、as、crossorigin、type 等属性是否配置正确。
  • 如果通过 CDN、Nginx 或网关发送 Early Hints,应确认中间层不会丢弃 1xx 响应。
  • 排查 103 Early Hints 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 103 当作接口成功响应;它只是提前发送资源提示。
  • 不要提前提示低命中率或体积很大的资源。
  • 不要在权限不确定的页面提前暴露敏感资源 URL。
来源: RFC 8297 相关状态码: 100, 102, 200, 204, 304, 404, 500
104

Upload Resumption Supported

服务器提示当前上传支持中断后的恢复续传。

1xx 信息性响应 临时 不建议作为公共 API 契约 draft-ietf-httpbis-resumable-upload-05
详情

104 Upload Resumption Supported 表示服务器在接收上传请求的过程中,提前告诉客户端当前目标资源支持 HTTP 可恢复上传机制。它属于 1xx 信息性状态码,用于 resumable upload 场景,目前在 IANA HTTP 状态码注册表中是临时注册状态,对应的是 HTTP 可恢复上传草案,而不是稳定 RFC。它的核心作用不是表示上传完成,而是让客户端知道:如果当前上传因为网络中断、页面关闭、连接重置或移动网络切换被打断,后续可以根据协议继续恢复上传。换句话说,当用户搜索“HTTP 104 是什么意思”、“104 Upload Resumption Supported 怎么解决”或“接口返回 104 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。信息性临时响应,重点是客户端不能把它当作最终结果。它来自 draft-ietf-httpbis-resumable-upload-05,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 客户端上传大文件、视频、压缩包、备份文件或其他长时间传输内容时,希望在网络中断后继续上传。
  • 服务端实现 HTTP 可恢复上传协议,需要在上传早期告知客户端当前请求支持 upload resumption。
  • 上传服务需要为客户端分配上传资源、恢复 URL、Upload-Offset 或续传状态。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 104 Upload Resumption Supported,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 104 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 客户端收到 104 后,不应认为上传已经完成,而应继续发送上传内容并等待最终响应。
  • 如果上传中断,客户端应根据服务端提供的恢复信息重新发起续传请求,并从确认的 Upload-Offset 位置继续发送剩余数据。
  • 如果经过代理、CDN 或负载均衡后 104 丢失,应检查中间层是否支持并透传 1xx 临时响应。
  • 排查 104 Upload Resumption Supported 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 104 当作上传成功;它只表示支持恢复上传。
  • 不要在没有 Upload-Offset、会话保存和恢复逻辑时返回 104。
  • 不要在普通文件上传或 JSON API 中随意使用 104。
来源: draft-ietf-httpbis-resumable-upload-05 相关状态码: 100, 102, 201, 202, 204, 206, 308, 409, 413, 416

2xx 成功响应

请求成功相关响应。选择更准确的成功状态码,可以区分已完成、已创建、已接受、无响应体和部分内容等不同语义。

200

OK

请求已成功处理,并返回了符合请求方法语义的响应。

2xx 成功响应 标准 推荐使用 RFC 9110
详情

200 OK 表示:请求已成功处理,并返回了符合请求方法语义的响应。它是标准 HTTP 状态码,适合用于业务查询成功、更新成功后返回结果、普通页面或 JSON API 正常响应。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 201, 202, 204 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 200 是什么意思”、“200 OK 怎么解决”或“接口返回 200 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 业务查询成功、更新成功后返回结果、普通页面或 JSON API 正常响应。
  • 客户端或调用方需要根据 200 OK 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 200 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 200 OK,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 200 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 200 OK,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 201, 202, 204, 304 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 200 OK 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 200 包装业务失败再在响应体里写 error=true。
  • 不要把所有成功都写成 200;创建、异步、无内容和缓存命中都有更精确的状态码。
  • 不要让搜索引擎看到 200 的错误页,否则软 404 会影响收录质量。
来源: RFC 9110 相关状态码: 201, 202, 204, 304, 400, 404, 500
201

Created

请求已经成功,并且服务器创建了新的资源。

2xx 成功响应 标准 推荐使用 RFC 9110
详情

201 Created 表示:请求已经成功,并且服务器创建了新的资源。它是标准 HTTP 状态码,适合用于创建用户、订单、文章、文件或其他资源后返回。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 202, 204 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 201 是什么意思”、“201 Created 怎么解决”或“接口返回 201 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 创建用户、订单、文章、文件或其他资源后返回。
  • 客户端或调用方需要根据 201 Created 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 201 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 201 Created,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 201 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 201 Created,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 202, 204, 303 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 201 Created 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在没有创建新资源时返回 201。
  • 不要把普通更新成功写成 201;更新更常见的是 200 或 204。
  • 不要创建失败还返回 201。
来源: RFC 9110 相关状态码: 200, 202, 204, 303, 409, 422
202

Accepted

请求已被接受处理,但处理尚未完成。

2xx 成功响应 标准 推荐使用 RFC 9110
详情

202 Accepted 表示:请求已被接受处理,但处理尚未完成。它是标准 HTTP 状态码,适合用于异步任务、排队任务、批量导入、耗时生成报表或后台处理。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 201, 204 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 202 是什么意思”、“202 Accepted 怎么解决”或“接口返回 202 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 异步任务、排队任务、批量导入、耗时生成报表或后台处理。
  • 客户端或调用方需要根据 202 Accepted 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 202 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 202 Accepted,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 202 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 202 Accepted,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 201, 204, 102 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 202 Accepted 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 202 当作任务已经成功完成。
  • 不要只返回 202 却不提供任务 ID、状态地址或查询方式。
  • 不要把同步创建成功误写成 202。
来源: RFC 9110 相关状态码: 200, 201, 204, 102, 303
203

Non-Authoritative Information

响应成功,但内容来自转换或代理后的非权威信息。

2xx 成功响应 标准 谨慎使用 RFC 9110
详情

203 Non-Authoritative Information 表示:响应成功,但内容来自转换或代理后的非权威信息。它是标准 HTTP 状态码,适合用于代理、网关、缓存系统对源站响应做了转换或补充。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 204, 304 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 203 是什么意思”、“203 Non-Authoritative Information 怎么解决”或“接口返回 203 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 代理、网关、缓存系统对源站响应做了转换或补充。
  • 客户端或调用方需要根据 203 Non-Authoritative Information 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 203 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 203 Non-Authoritative Information,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 203 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 203 Non-Authoritative Information,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 204, 304 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 203 Non-Authoritative Information 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在内容没有被代理或转换层改写时返回 203。
  • 不要用 203 掩盖代理层造成的数据不一致。
  • 普通 API 成功响应通常用 200 更容易理解。
来源: RFC 9110 相关状态码: 200, 204, 304
204

No Content

请求成功,但响应不需要返回消息体。

2xx 成功响应 标准 推荐使用 RFC 9110
详情

204 No Content 表示:请求成功,但响应不需要返回消息体。它是标准 HTTP 状态码,适合用于删除成功、开关更新成功、保存成功但页面不需要刷新数据。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 201, 202 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 204 是什么意思”、“204 No Content 怎么解决”或“接口返回 204 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 删除成功、开关更新成功、保存成功但页面不需要刷新数据。
  • 客户端或调用方需要根据 204 No Content 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 204 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 204 No Content,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 204 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 204 No Content,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 201, 202, 205 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 204 No Content 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在 204 响应里返回 JSON body。
  • 不要在客户端需要更新后数据时返回 204。
  • 不要用 204 表示异步任务已经开始。
来源: RFC 9110 相关状态码: 200, 201, 202, 205
205

Reset Content

请求成功,客户端应重置当前输入视图或表单。

2xx 成功响应 标准 谨慎使用 RFC 9110
详情

205 Reset Content 表示:请求成功,客户端应重置当前输入视图或表单。它是标准 HTTP 状态码,适合用于提交表单后希望客户端清空输入状态。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 204 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 205 是什么意思”、“205 Reset Content 怎么解决”或“接口返回 205 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 提交表单后希望客户端清空输入状态。
  • 客户端或调用方需要根据 205 Reset Content 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 205 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 205 Reset Content,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 205 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 205 Reset Content,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 204 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 205 Reset Content 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在不希望客户端重置表单或输入视图时返回 205。
  • 不要在 205 里放需要客户端解析的业务数据。
  • 普通 API 很少需要 205,除非你明确设计了重置界面语义。
来源: RFC 9110 相关状态码: 200, 204
206

Partial Content

服务器按 Range 请求返回了资源的一部分。

2xx 成功响应 标准 谨慎使用 RFC 9110
详情

206 Partial Content 表示:服务器按 Range 请求返回了资源的一部分。它是标准 HTTP 状态码,适合用于断点下载、视频拖动播放、分片读取大文件。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 304, 416 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 206 是什么意思”、“206 Partial Content 怎么解决”或“接口返回 206 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 断点下载、视频拖动播放、分片读取大文件。
  • 客户端或调用方需要根据 206 Partial Content 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 206 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 206 Partial Content,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 206 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 206 Partial Content,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 304, 416 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 206 Partial Content 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 206 用于普通分页列表,分页通常还是 200。
  • 不要在没有 Range 请求时返回 206。
  • 不要遗漏 Content-Range,否则客户端下载和视频播放很容易出错。
来源: RFC 9110 相关状态码: 200, 304, 416
207

Multi-Status

响应中包含多个资源或多个操作的独立状态结果。

2xx 成功响应 标准 不建议作为公共 API 契约 RFC 4918
详情

207 Multi-Status 表示:响应中包含多个资源或多个操作的独立状态结果。它是扩展状态码,适合用于WebDAV 批量资源操作、集合操作、多文件处理。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 206, 208 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 207 是什么意思”、“207 Multi-Status 怎么解决”或“接口返回 207 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 4918,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • WebDAV 批量资源操作、集合操作、多文件处理。
  • 客户端或调用方需要根据 207 Multi-Status 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 207 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 207 Multi-Status,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 207 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 207 Multi-Status,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 206, 208, 424 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 207 Multi-Status 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 207 当成全部成功,必须查看每个子资源的状态。
  • 普通批量 JSON API 不一定要使用 WebDAV 的 207。
  • 不要只返回 207 却没有逐项结果。
来源: RFC 4918 相关状态码: 200, 206, 208, 424
208

Already Reported

同一 WebDAV 绑定中的成员已经在前面报告过。

2xx 成功响应 标准 不建议作为公共 API 契约 RFC 5842
详情

208 Already Reported 表示:同一 WebDAV 绑定中的成员已经在前面报告过。它是扩展状态码,适合用于WebDAV depth 请求中避免重复枚举同一个资源。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 207, 226, 508 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 208 是什么意思”、“208 Already Reported 怎么解决”或“接口返回 208 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 5842,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • WebDAV depth 请求中避免重复枚举同一个资源。
  • 客户端或调用方需要根据 208 Already Reported 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 208 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 208 Already Reported,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 208 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 208 Already Reported,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 207, 226, 508 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 208 Already Reported 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 208 用来表示业务重复提交。
  • 不要在非 WebDAV 绑定场景使用 208。
  • 不要把 208 当成缓存命中或幂等成功。
来源: RFC 5842 相关状态码: 207, 226, 508
226

IM Used

服务器返回的是对当前实例应用增量编码后的结果。

2xx 成功响应 标准 不建议作为公共 API 契约 RFC 3229
详情

226 IM Used 表示:服务器返回的是对当前实例应用增量编码后的结果。它是扩展状态码,适合用于HTTP Delta Encoding,客户端和服务端都支持实例增量传输。。理解这个状态码时,关键不是只看数字属于 2xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 206, 304 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 226 是什么意思”、“226 IM Used 怎么解决”或“接口返回 226 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。成功响应,重点是区分“已经完成、已经创建、只被接受、没有响应体、只返回部分内容”等不同成功语义。它来自 RFC 3229,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • HTTP Delta Encoding,客户端和服务端都支持实例增量传输。
  • 客户端或调用方需要根据 226 IM Used 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 226 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 226 IM Used,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 226 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 226 IM Used,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 206, 304 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 226 IM Used 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 226 当作普通部分下载;Range 分片更接近 206。
  • 不要在客户端不支持增量编码时返回 226。
  • 普通 JSON API 基本不需要 226。
来源: RFC 3229 相关状态码: 200, 206, 304

3xx 重定向响应

重定向和缓存相关响应,会影响浏览器跳转、搜索引擎抓取、规范化 URL、API 客户端和重试行为。

300

Multiple Choices

目标资源有多个可选表示,客户端或用户需要选择其中一个。

3xx 重定向响应 标准 谨慎使用 RFC 9110
详情

300 Multiple Choices 表示:目标资源有多个可选表示,客户端或用户需要选择其中一个。它是标准 HTTP 状态码,适合用于同一资源存在多语言、多格式或多个镜像地址。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 301, 302, 303 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 300 是什么意思”、“300 Multiple Choices 怎么解决”或“接口返回 300 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 同一资源存在多语言、多格式或多个镜像地址。
  • 客户端或调用方需要根据 300 Multiple Choices 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 300 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 300 Multiple Choices,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 300 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 300 Multiple Choices,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 301, 302, 303, 406 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 300 Multiple Choices 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在只有一个明确目标时返回 300。
  • 不要返回 300 却不给候选链接。
  • SEO 页面不要让用户和搜索引擎面对不明确的多选入口。
来源: RFC 9110 相关状态码: 301, 302, 303, 406
301

Moved Permanently

资源已经永久移动到新的 URL。

3xx 重定向响应 标准 推荐使用 RFC 9110
详情

301 Moved Permanently 表示:资源已经永久移动到新的 URL。它是标准 HTTP 状态码,适合用于网站改版、URL 规范化、HTTP 到 HTTPS 的永久跳转。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 302, 307, 308 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 301 是什么意思”、“301 Moved Permanently 怎么解决”或“接口返回 301 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 网站改版、URL 规范化、HTTP 到 HTTPS 的永久跳转。
  • 客户端或调用方需要根据 301 Moved Permanently 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 301 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 301 Moved Permanently,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 301 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 301 Moved Permanently,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 302, 307, 308, 404 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 301 Moved Permanently 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把临时活动页或 A/B 测试写成 301。
  • 不要把所有 404 都 301 到首页。
  • 对 POST/PUT 等需要保留方法的永久迁移,308 可能比 301 更准确。
来源: RFC 9110 相关状态码: 302, 307, 308, 404, 410
302

Found

资源临时位于另一个 URL,客户端可以临时跳转。

3xx 重定向响应 标准 推荐使用 RFC 9110
详情

302 Found 表示:资源临时位于另一个 URL,客户端可以临时跳转。它是标准 HTTP 状态码,适合用于临时活动页、登录后跳回、A/B 测试或短期迁移。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 301, 303, 307 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 302 是什么意思”、“302 Found 怎么解决”或“接口返回 302 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 临时活动页、登录后跳回、A/B 测试或短期迁移。
  • 客户端或调用方需要根据 302 Found 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 302 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 302 Found,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 302 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 302 Found,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 301, 303, 307, 308 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 302 Found 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 302 做永久迁移。
  • 不要让 API 的认证失败跳到 HTML 登录页;开放 API 更适合 401。
  • 不要制造多层 302 跳转链。
来源: RFC 9110 相关状态码: 301, 303, 307, 308
303

See Other

客户端应使用 GET 请求另一个 URL 查看结果。

3xx 重定向响应 标准 谨慎使用 RFC 9110
详情

303 See Other 表示:客户端应使用 GET 请求另一个 URL 查看结果。它是标准 HTTP 状态码,适合用于POST 创建或提交后跳转到结果页,避免刷新重复提交。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 201, 202, 302 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 303 是什么意思”、“303 See Other 怎么解决”或“接口返回 303 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • POST 创建或提交后跳转到结果页,避免刷新重复提交。
  • 客户端或调用方需要根据 303 See Other 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 303 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 303 See Other,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 303 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 303 See Other,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 201, 202, 302, 307 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 303 See Other 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 303 表示永久迁移。
  • 不要让 Location 指向不能 GET 的接口。
  • 如果必须保留原请求方法,不要用 303。
来源: RFC 9110 相关状态码: 201, 202, 302, 307
304

Not Modified

资源未修改,客户端可以继续使用缓存副本。

3xx 重定向响应 标准 推荐使用 RFC 9110
详情

304 Not Modified 表示:资源未修改,客户端可以继续使用缓存副本。它是标准 HTTP 状态码,适合用于条件请求、浏览器缓存、ETag 或 Last-Modified 校验命中。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 204, 206 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 304 是什么意思”、“304 Not Modified 怎么解决”或“接口返回 304 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 条件请求、浏览器缓存、ETag 或 Last-Modified 校验命中。
  • 客户端或调用方需要根据 304 Not Modified 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 304 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 304 Not Modified,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 304 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 304 Not Modified,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 204, 206, 412 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 304 Not Modified 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在没有条件请求时返回 304。
  • 不要给 304 返回完整响应体。
  • 不要让错误的缓存头导致用户长期看到旧内容。
来源: RFC 9110 相关状态码: 200, 204, 206, 412
305

Use Proxy

请求资源必须通过代理访问。

3xx 重定向响应 标准 不建议作为公共 API 契约 RFC 9110
详情

305 Use Proxy 表示:请求资源必须通过代理访问。它是历史或保留状态码,适合用于历史代理机制,现代浏览器和 API 基本不再使用。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 300, 307, 308 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 305 是什么意思”、“305 Use Proxy 怎么解决”或“接口返回 305 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 历史代理机制,现代浏览器和 API 基本不再使用。
  • 客户端或调用方需要根据 305 Use Proxy 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 305 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 305 Use Proxy,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 305 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 305 Use Proxy,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 300, 307, 308 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 305 Use Proxy 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在新系统中使用 305。
  • 不要把 305 当普通重定向。
  • 不要通过响应强迫客户端使用不可信代理。
来源: RFC 9110 相关状态码: 300, 307, 308
306

Unused

历史保留状态码,目前不再使用。

3xx 重定向响应 保留 不建议作为公共 API 契约 RFC 9110
详情

306 Unused 表示:历史保留状态码,目前不再使用。它是历史或保留状态码,适合用于仅用于解释历史兼容性,不应用于新系统。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 305, 307 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 306 是什么意思”、“306 Unused 怎么解决”或“接口返回 306 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 仅用于解释历史兼容性,不应用于新系统。
  • 客户端或调用方需要根据 306 Unused 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 306 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 306 Unused,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 306 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 306 Unused,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 305, 307 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 306 Unused 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在业务接口中返回 306。
  • 不要给 306 自定义新的公开语义。
  • 不要把 306 当作可用的重定向状态码。
来源: RFC 9110 相关状态码: 305, 307
307

Temporary Redirect

资源临时重定向,并且客户端不应改变请求方法。

3xx 重定向响应 标准 推荐使用 RFC 9110
详情

307 Temporary Redirect 表示:资源临时重定向,并且客户端不应改变请求方法。它是标准 HTTP 状态码,适合用于临时迁移 POST/PUT 接口、维护切流、保留原方法的短期跳转。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 302, 303, 308 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 307 是什么意思”、“307 Temporary Redirect 怎么解决”或“接口返回 307 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 临时迁移 POST/PUT 接口、维护切流、保留原方法的短期跳转。
  • 客户端或调用方需要根据 307 Temporary Redirect 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 307 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 307 Temporary Redirect,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 307 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 307 Temporary Redirect,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 302, 303, 308 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 307 Temporary Redirect 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 307 做永久迁移。
  • 不要在目标接口不支持原方法时使用 307。
  • 不要用 307 代替登录或权限错误。
来源: RFC 9110 相关状态码: 302, 303, 308
308

Permanent Redirect

资源永久重定向,并且客户端不应改变请求方法。

3xx 重定向响应 标准 推荐使用 RFC 9110
详情

308 Permanent Redirect 表示:资源永久重定向,并且客户端不应改变请求方法。它是标准 HTTP 状态码,适合用于永久迁移 API 地址、保留 POST/PUT 方法的 HTTPS 或域名迁移。。理解这个状态码时,关键不是只看数字属于 3xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 301, 307 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 308 是什么意思”、“308 Permanent Redirect 怎么解决”或“接口返回 308 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。重定向或缓存相关响应,重点是 Location、缓存条件、请求方法是否保持以及搜索引擎如何理解跳转。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 永久迁移 API 地址、保留 POST/PUT 方法的 HTTPS 或域名迁移。
  • 客户端或调用方需要根据 308 Permanent Redirect 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 308 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 308 Permanent Redirect,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 308 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 308 Permanent Redirect,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 301, 307 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 308 Permanent Redirect 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把临时迁移写成 308。
  • 不要在新地址还不稳定时使用 308。
  • 不要制造 308 循环或长跳转链。
来源: RFC 9110 相关状态码: 301, 307

4xx 客户端错误

客户端请求侧问题,包括语法错误、认证、授权、资源不存在、参数校验、状态冲突、限流或法律限制。

400

Bad Request

请求语法、格式或基础参数错误,服务器无法理解或处理。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

400 Bad Request 表示:请求语法、格式或基础参数错误,服务器无法理解或处理。它是标准 HTTP 状态码,适合用于JSON 解析失败、参数类型错误、必填字段缺失、URL 格式错误。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 401, 403, 404 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 400 是什么意思”、“400 Bad Request 怎么解决”或“接口返回 400 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • JSON 解析失败、参数类型错误、必填字段缺失、URL 格式错误。
  • 客户端或调用方需要根据 400 Bad Request 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 400 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 400 Bad Request,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 400 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 400 Bad Request,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 401, 403, 404, 409 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 400 Bad Request 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把所有客户端错误都返回 400。
  • 不要用 400 表示服务端异常。
  • 不要只写 Bad Request,要说明哪个字段、格式或请求部分有问题。
来源: RFC 9110 相关状态码: 401, 403, 404, 409, 422
401

Unauthorized

请求缺少有效身份认证,客户端需要先登录或提供凭据。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

401 Unauthorized 表示:请求缺少有效身份认证,客户端需要先登录或提供凭据。它是标准 HTTP 状态码,适合用于未登录、Token 缺失、Token 过期、认证头格式错误。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 403, 407, 419 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 401 是什么意思”、“401 Unauthorized 怎么解决”或“接口返回 401 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 未登录、Token 缺失、Token 过期、认证头格式错误。
  • 客户端或调用方需要根据 401 Unauthorized 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 401 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 401 Unauthorized,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 401 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 401 Unauthorized,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 403, 407, 419, 440 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 401 Unauthorized 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 401 表示已登录用户没有权限;那更接近 403。
  • 不要把业务校验失败写成 401。
  • 不要在响应里暴露过多认证细节。
来源: RFC 9110 相关状态码: 403, 407, 419, 440
402

Payment Required

保留给支付相关场景,标准语义尚未被广泛定义。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

402 Payment Required 表示:保留给支付相关场景,标准语义尚未被广泛定义。它是标准 HTTP 状态码,适合用于付费 API、额度不足、订阅失效等自定义业务场景。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 403, 429 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 402 是什么意思”、“402 Payment Required 怎么解决”或“接口返回 402 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 付费 API、额度不足、订阅失效等自定义业务场景。
  • 客户端或调用方需要根据 402 Payment Required 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 402 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 402 Payment Required,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 402 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 402 Payment Required,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 403, 429 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 402 Payment Required 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把所有商业限制都写成 402。
  • 不要在没有支付、订阅或额度语义时使用 402。
  • 不要假设客户端会对 402 有统一内置处理。
来源: RFC 9110 相关状态码: 403, 429
403

Forbidden

服务器理解请求,也知道用户是谁,但拒绝执行。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

403 Forbidden 表示:服务器理解请求,也知道用户是谁,但拒绝执行。它是标准 HTTP 状态码,适合用于权限不足、IP 被拒绝、资源不允许当前角色访问。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 401, 404, 451 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 403 是什么意思”、“403 Forbidden 怎么解决”或“接口返回 403 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 权限不足、IP 被拒绝、资源不允许当前角色访问。
  • 客户端或调用方需要根据 403 Forbidden 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 403 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 403 Forbidden,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 403 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 403 Forbidden,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 401, 404, 451 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 403 Forbidden 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 403 表示未登录;未认证通常是 401。
  • 不要把资源不存在随意写成 403。
  • 不要在响应中泄露敏感权限策略。
来源: RFC 9110 相关状态码: 401, 404, 451
404

Not Found

服务器找不到目标资源,或不愿透露资源是否存在。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

404 Not Found 表示:服务器找不到目标资源,或不愿透露资源是否存在。它是标准 HTTP 状态码,适合用于URL 不存在、资源 ID 不存在、路由未匹配、隐藏敏感资源。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 403, 410 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 404 是什么意思”、“404 Not Found 怎么解决”或“接口返回 404 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • URL 不存在、资源 ID 不存在、路由未匹配、隐藏敏感资源。
  • 客户端或调用方需要根据 404 Not Found 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 404 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 404 Not Found,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 404 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 404 Not Found,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 403, 410 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 404 Not Found 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把所有错误都返回 404。
  • 不要把永久迁移资源返回 404,应考虑 301 或 308。
  • 不要让前端路由把 API 的真实 404 吞掉。
来源: RFC 9110 相关状态码: 400, 403, 410
405

Method Not Allowed

目标资源存在,但不支持当前 HTTP 方法。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

405 Method Not Allowed 表示:目标资源存在,但不支持当前 HTTP 方法。它是标准 HTTP 状态码,适合用于对只读资源发送 POST,对只支持 POST 的接口发送 GET。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 404, 501 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 405 是什么意思”、“405 Method Not Allowed 怎么解决”或“接口返回 405 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 对只读资源发送 POST,对只支持 POST 的接口发送 GET。
  • 客户端或调用方需要根据 405 Method Not Allowed 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 405 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 405 Method Not Allowed,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 405 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 405 Method Not Allowed,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 404, 501 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 405 Method Not Allowed 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 405 表示资源不存在。
  • 不要返回 405 却不提供 Allow 头。
  • 不要把权限不足写成 405。
来源: RFC 9110 相关状态码: 400, 404, 501
406

Not Acceptable

服务器无法提供客户端 Accept 头所要求的表示形式。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

406 Not Acceptable 表示:服务器无法提供客户端 Accept 头所要求的表示形式。它是标准 HTTP 状态码,适合用于客户端只接受 XML、特定语言或特定媒体类型,而服务端无法满足。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 300, 415 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 406 是什么意思”、“406 Not Acceptable 怎么解决”或“接口返回 406 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 客户端只接受 XML、特定语言或特定媒体类型,而服务端无法满足。
  • 客户端或调用方需要根据 406 Not Acceptable 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 406 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 406 Not Acceptable,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 406 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 406 Not Acceptable,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 300, 415 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 406 Not Acceptable 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把请求体 Content-Type 错误写成 406;那更接近 415。
  • 不要在简单 JSON API 中过度使用 406。
  • 不要返回 406 却不说明服务端支持哪些格式。
来源: RFC 9110 相关状态码: 300, 415
407

Proxy Authentication Required

请求需要先通过代理服务器认证。

4xx 客户端错误 标准 不建议作为公共 API 契约 RFC 9110
详情

407 Proxy Authentication Required 表示:请求需要先通过代理服务器认证。它是标准 HTTP 状态码,适合用于企业代理、正向代理、网关代理要求认证。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 401, 403 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 407 是什么意思”、“407 Proxy Authentication Required 怎么解决”或“接口返回 407 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 企业代理、正向代理、网关代理要求认证。
  • 客户端或调用方需要根据 407 Proxy Authentication Required 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 407 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 407 Proxy Authentication Required,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 407 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 407 Proxy Authentication Required,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 401, 403 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 407 Proxy Authentication Required 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 普通业务应用不要主动返回 407。
  • 不要把网站登录失败写成 407。
  • 不要在没有代理认证机制的系统中使用 407。
来源: RFC 9110 相关状态码: 401, 403
408

Request Timeout

服务器等待客户端发送请求的时间过长。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

408 Request Timeout 表示:服务器等待客户端发送请求的时间过长。它是标准 HTTP 状态码,适合用于客户端网络慢、请求体上传超时、连接空闲过久。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 499, 504 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 408 是什么意思”、“408 Request Timeout 怎么解决”或“接口返回 408 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 客户端网络慢、请求体上传超时、连接空闲过久。
  • 客户端或调用方需要根据 408 Request Timeout 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 408 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 408 Request Timeout,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 408 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 408 Request Timeout,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 499, 504 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 408 Request Timeout 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 408 表示服务端处理太慢。
  • 不要把所有客户端断开都写成 408;Nginx 日志中常见的是 499。
  • 不要用 408 掩盖上传大小限制问题。
来源: RFC 9110 相关状态码: 400, 499, 504
409

Conflict

请求与资源当前状态冲突,服务器不能直接完成。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

409 Conflict 表示:请求与资源当前状态冲突,服务器不能直接完成。它是标准 HTTP 状态码,适合用于版本冲突、重复提交、资源状态不允许当前操作、并发更新失败。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 412, 422 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 409 是什么意思”、“409 Conflict 怎么解决”或“接口返回 409 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 版本冲突、重复提交、资源状态不允许当前操作、并发更新失败。
  • 客户端或调用方需要根据 409 Conflict 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 409 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 409 Conflict,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 409 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 409 Conflict,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 412, 422, 423 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 409 Conflict 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把所有业务错误都返回 409。
  • 不要用 409 表示 JSON 格式错误。
  • 不要返回 409 却不说明冲突点和恢复方式。
来源: RFC 9110 相关状态码: 400, 412, 422, 423
410

Gone

资源曾经存在,但现在已经永久不可用。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

410 Gone 表示:资源曾经存在,但现在已经永久不可用。它是标准 HTTP 状态码,适合用于内容下架、旧 API 废弃、文章永久删除且不再恢复。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 404, 301, 451 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 410 是什么意思”、“410 Gone 怎么解决”或“接口返回 410 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 内容下架、旧 API 废弃、文章永久删除且不再恢复。
  • 客户端或调用方需要根据 410 Gone 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 410 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 410 Gone,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 410 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 410 Gone,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 404, 301, 451 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 410 Gone 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在临时不可用时使用 410。
  • 不要对从未存在的资源强行使用 410。
  • 不要用 410 表示法律限制;法律原因更适合 451。
来源: RFC 9110 相关状态码: 404, 301, 451
411

Length Required

服务器要求请求必须提供 Content-Length。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

411 Length Required 表示:服务器要求请求必须提供 Content-Length。它是标准 HTTP 状态码,适合用于服务端不接受没有长度信息的请求体或分块传输。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 413 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 411 是什么意思”、“411 Length Required 怎么解决”或“接口返回 411 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 服务端不接受没有长度信息的请求体或分块传输。
  • 客户端或调用方需要根据 411 Length Required 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 411 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 411 Length Required,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 411 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 411 Length Required,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 413 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 411 Length Required 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在没有请求体的请求上返回 411。
  • 不要把请求体过大写成 411。
  • 不要让代理或 SDK 误删 Content-Length。
来源: RFC 9110 相关状态码: 400, 413
412

Precondition Failed

条件请求中的前置条件没有通过。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

412 Precondition Failed 表示:条件请求中的前置条件没有通过。它是标准 HTTP 状态码,适合用于If-Match、If-Unmodified-Since、ETag 乐观锁校验失败。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 304, 409, 428 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 412 是什么意思”、“412 Precondition Failed 怎么解决”或“接口返回 412 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • If-Match、If-Unmodified-Since、ETag 乐观锁校验失败。
  • 客户端或调用方需要根据 412 Precondition Failed 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 412 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 412 Precondition Failed,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 412 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 412 Precondition Failed,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 304, 409, 428 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 412 Precondition Failed 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把普通字段校验失败写成 412。
  • 不要在没有条件请求头的场景随意返回 412。
  • 不要忽略 ETag 或版本号的一致性。
来源: RFC 9110 相关状态码: 304, 409, 428
413

Content Too Large

请求内容超过服务器允许的大小。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

413 Content Too Large 表示:请求内容超过服务器允许的大小。它是标准 HTTP 状态码,适合用于上传文件过大、JSON 请求体过大、表单数据超过限制。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 411, 415 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 413 是什么意思”、“413 Content Too Large 怎么解决”或“接口返回 413 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 上传文件过大、JSON 请求体过大、表单数据超过限制。
  • 客户端或调用方需要根据 413 Content Too Large 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 413 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 413 Content Too Large,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 413 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 413 Content Too Large,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 411, 415 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 413 Content Too Large 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 413 表示字段格式错误。
  • 不要只改应用层限制而忽略 Nginx、CDN 或网关限制。
  • 不要让前端在没有大小提示的情况下反复上传超大文件。
来源: RFC 9110 相关状态码: 400, 411, 415
414

URI Too Long

请求 URI 过长,服务器无法或不愿处理。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

414 URI Too Long 表示:请求 URI 过长,服务器无法或不愿处理。它是标准 HTTP 状态码,适合用于GET 查询参数过多、把大量数据放在 URL 中、重定向循环导致 URL 膨胀。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 431 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 414 是什么意思”、“414 URI Too Long 怎么解决”或“接口返回 414 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • GET 查询参数过多、把大量数据放在 URL 中、重定向循环导致 URL 膨胀。
  • 客户端或调用方需要根据 414 URI Too Long 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 414 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 414 URI Too Long,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 414 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 414 URI Too Long,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 431 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 414 URI Too Long 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把请求体过大写成 414。
  • 不要把 Cookie 过大写成 414;请求头过大更接近 431 或 494。
  • 不要用超长 URL 传递敏感或大量数据。
来源: RFC 9110 相关状态码: 400, 431
415

Unsupported Media Type

服务器不支持请求体的媒体类型或编码格式。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

415 Unsupported Media Type 表示:服务器不支持请求体的媒体类型或编码格式。它是标准 HTTP 状态码,适合用于Content-Type 错误、上传格式不支持、压缩编码无法处理。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 406, 422 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 415 是什么意思”、“415 Unsupported Media Type 怎么解决”或“接口返回 415 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • Content-Type 错误、上传格式不支持、压缩编码无法处理。
  • 客户端或调用方需要根据 415 Unsupported Media Type 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 415 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 415 Unsupported Media Type,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 415 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 415 Unsupported Media Type,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 406, 422 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 415 Unsupported Media Type 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把响应格式不可接受写成 415;那更接近 406。
  • 不要把 JSON 语法错误都写成 415。
  • 不要只返回 415 却不说明支持哪些媒体类型。
来源: RFC 9110 相关状态码: 400, 406, 422
416

Range Not Satisfiable

Range 请求的范围无法满足。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

416 Range Not Satisfiable 表示:Range 请求的范围无法满足。它是标准 HTTP 状态码,适合用于断点下载范围超出文件大小、视频播放器请求无效字节区间。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 200, 206 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 416 是什么意思”、“416 Range Not Satisfiable 怎么解决”或“接口返回 416 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 断点下载范围超出文件大小、视频播放器请求无效字节区间。
  • 客户端或调用方需要根据 416 Range Not Satisfiable 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 416 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 416 Range Not Satisfiable,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 416 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 416 Range Not Satisfiable,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 200, 206 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 416 Range Not Satisfiable 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在普通分页 API 中使用 416。
  • 不要在没有 Range 请求时返回 416。
  • 不要把资源不存在写成 416。
来源: RFC 9110 相关状态码: 200, 206
417

Expectation Failed

服务器无法满足 Expect 请求头中的期望。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

417 Expectation Failed 表示:服务器无法满足 Expect 请求头中的期望。它是标准 HTTP 状态码,适合用于Expect: 100-continue 被服务端或代理拒绝。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 100, 400, 413 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 417 是什么意思”、“417 Expectation Failed 怎么解决”或“接口返回 417 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • Expect: 100-continue 被服务端或代理拒绝。
  • 客户端或调用方需要根据 417 Expectation Failed 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 417 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 417 Expectation Failed,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 417 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 417 Expectation Failed,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 100, 400, 413 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 417 Expectation Failed 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 417 表示普通业务规则失败。
  • 不要在没有 Expect 请求头时返回 417。
  • 不要把上传完成后的处理失败写成 417。
来源: RFC 9110 相关状态码: 100, 400, 413
418

I'm a teapot

彩蛋状态码,表示服务器是茶壶而不能冲咖啡。

4xx 客户端错误 保留 不建议作为公共 API 契约 RFC 9110
详情

418 I'm a teapot 表示:彩蛋状态码,表示服务器是茶壶而不能冲咖啡。它是历史或保留状态码,适合用于幽默页面、开发者彩蛋、测试文档。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 501 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 418 是什么意思”、“418 I'm a teapot 怎么解决”或“接口返回 418 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 幽默页面、开发者彩蛋、测试文档。
  • 客户端或调用方需要根据 418 I'm a teapot 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 418 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 418 I'm a teapot,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 418 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 418 I'm a teapot,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 501 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 418 I'm a teapot 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在正式 API 中把 418 当作业务错误码。
  • 不要用 418 表示功能未实现;501 更合适。
  • 不要让重要页面返回 418。
来源: RFC 9110 相关状态码: 400, 501
419

Page Expired

页面或会话已过期,常见于 CSRF Token 失效。

4xx 客户端错误 非标准 谨慎使用 Laravel
详情

419 Page Expired 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:页面或会话已过期,常见于 CSRF Token 失效。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Laravel 等框架在表单 Token、登录会话或页面状态过期时使用。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 419 是什么意思”、“419 Page Expired 怎么解决”或“接口返回 419 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Laravel 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Laravel 等框架在表单 Token、登录会话或页面状态过期时使用。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 419 Page Expired,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 419 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 419 是否由 Laravel 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 401, 403,并在响应体里保留更细的内部错误码。
  • 排查 419 Page Expired 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把所有未登录都写成 419;标准认证问题更接近 401。
  • 不要要求第三方 API 客户端理解 419。
  • 不要只提示页面过期而不给用户刷新或重新登录的路径。
来源: Laravel 相关状态码: 400, 401, 403, 440, 422
420

Enhance Your Calm

客户端请求过于频繁或行为异常,历史上常被用作非标准限流提示。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Twitter legacy / non-standard convention
详情

420 Enhance Your Calm 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:客户端请求过于频繁或行为异常,历史上常被用作非标准限流提示。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于旧 Twitter API、部分服务的自定义限流或滥用保护。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 420 是什么意思”、“420 Enhance Your Calm 怎么解决”或“接口返回 420 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Twitter legacy / non-standard convention,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 旧 Twitter API、部分服务的自定义限流或滥用保护。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 420 Enhance Your Calm,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 420 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 420 是否由 Twitter legacy / non-standard convention 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 429, 403, 503,并在响应体里保留更细的内部错误码。
  • 排查 420 Enhance Your Calm 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在新 API 中使用 420;限流应优先使用 429。
  • 不要让客户端依赖这个历史状态码。
  • 不要把普通权限拒绝写成 420。
421

Misdirected Request

请求被发送到了不能为目标权威处理该请求的服务器。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

421 Misdirected Request 表示:请求被发送到了不能为目标权威处理该请求的服务器。它是标准 HTTP 状态码,适合用于HTTP/2 连接复用、SNI、反向代理或多域名配置错误。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 421, 502 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 421 是什么意思”、“421 Misdirected Request 怎么解决”或“接口返回 421 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • HTTP/2 连接复用、SNI、反向代理或多域名配置错误。
  • 客户端或调用方需要根据 421 Misdirected Request 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 421 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 421 Misdirected Request,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 421 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 421 Misdirected Request,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 421, 502 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 421 Misdirected Request 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把普通路由不存在写成 421。
  • 不要用 421 表示权限问题。
  • 不要忽略 SNI、多域名连接复用和反向代理路由错误。
来源: RFC 9110 相关状态码: 400, 421, 502
422

Unprocessable Content

请求格式正确,但语义或业务规则无法通过。

4xx 客户端错误 标准 推荐使用 RFC 9110
详情

422 Unprocessable Content 表示:请求格式正确,但语义或业务规则无法通过。它是标准 HTTP 状态码,适合用于表单校验失败、邮箱已存在、库存不足、字段语义不合法。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 409, 415 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 422 是什么意思”、“422 Unprocessable Content 怎么解决”或“接口返回 422 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 表单校验失败、邮箱已存在、库存不足、字段语义不合法。
  • 客户端或调用方需要根据 422 Unprocessable Content 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 422 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 422 Unprocessable Content,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 422 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 422 Unprocessable Content,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 409, 415 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 422 Unprocessable Content 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 JSON 语法错误写成 422;那更接近 400。
  • 不要把权限不足写成 422。
  • 不要只返回 422 却不给字段级错误详情。
来源: RFC 9110 相关状态码: 400, 409, 415
423

Locked

目标资源被锁定,当前请求不能修改它。

4xx 客户端错误 标准 谨慎使用 RFC 4918
详情

423 Locked 表示:目标资源被锁定,当前请求不能修改它。它是扩展状态码,适合用于WebDAV 锁、文档协作锁、文件正在被其他操作占用。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 409, 424, 507 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 423 是什么意思”、“423 Locked 怎么解决”或“接口返回 423 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 4918,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • WebDAV 锁、文档协作锁、文件正在被其他操作占用。
  • 客户端或调用方需要根据 423 Locked 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 423 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 423 Locked,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 423 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 423 Locked,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 409, 424, 507 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 423 Locked 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把普通权限不足写成 423。
  • 不要在没有锁机制的系统中使用 423。
  • 不要返回 423 却不说明锁定原因或恢复方式。
来源: RFC 4918 相关状态码: 409, 424, 507
424

Failed Dependency

请求因依赖的前置操作失败而无法执行。

4xx 客户端错误 标准 不建议作为公共 API 契约 RFC 4918
详情

424 Failed Dependency 表示:请求因依赖的前置操作失败而无法执行。它是扩展状态码,适合用于WebDAV 批处理中的前一步失败,导致后续操作不能继续。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 207, 409, 423 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 424 是什么意思”、“424 Failed Dependency 怎么解决”或“接口返回 424 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 4918,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • WebDAV 批处理中的前一步失败,导致后续操作不能继续。
  • 客户端或调用方需要根据 424 Failed Dependency 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 424 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 424 Failed Dependency,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 424 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 424 Failed Dependency,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 207, 409, 423 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 424 Failed Dependency 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 424 表示普通参数缺失。
  • 不要隐藏真正失败的前置操作。
  • 普通 API 不建议使用 424,除非确实在表达批处理依赖失败。
来源: RFC 4918 相关状态码: 207, 409, 423
425

Too Early

服务器不愿处理可能被重放的早期数据请求。

4xx 客户端错误 标准 谨慎使用 RFC 8470
详情

425 Too Early 表示:服务器不愿处理可能被重放的早期数据请求。它是标准 HTTP 状态码,适合用于TLS 0-RTT early data 中的非幂等请求,可能被重放。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 409, 429 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 425 是什么意思”、“425 Too Early 怎么解决”或“接口返回 425 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 8470,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • TLS 0-RTT early data 中的非幂等请求,可能被重放。
  • 客户端或调用方需要根据 425 Too Early 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 425 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 425 Too Early,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 425 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 425 Too Early,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 409, 429 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 425 Too Early 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 425 表示服务繁忙。
  • 不要把普通限流写成 425;限流更接近 429。
  • 不要在不了解 TLS 0-RTT 重放风险时随意使用。
来源: RFC 8470 相关状态码: 400, 409, 429
426

Upgrade Required

服务器要求客户端切换到其他协议后再请求。

4xx 客户端错误 标准 谨慎使用 RFC 9110
详情

426 Upgrade Required 表示:服务器要求客户端切换到其他协议后再请求。它是标准 HTTP 状态码,适合用于要求升级到 TLS、HTTP/2、WebSocket 或其他协议能力。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 101, 400, 505 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 426 是什么意思”、“426 Upgrade Required 怎么解决”或“接口返回 426 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 要求升级到 TLS、HTTP/2、WebSocket 或其他协议能力。
  • 客户端或调用方需要根据 426 Upgrade Required 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 426 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 426 Upgrade Required,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 426 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 426 Upgrade Required,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 101, 400, 505 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 426 Upgrade Required 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 426 做普通重定向。
  • 不要返回 426 却不告诉客户端需要升级到什么协议。
  • 不要把认证或权限问题写成 426。
来源: RFC 9110 相关状态码: 101, 400, 505
428

Precondition Required

服务器要求请求必须带条件头以避免并发覆盖。

4xx 客户端错误 标准 推荐使用 RFC 6585
详情

428 Precondition Required 表示:服务器要求请求必须带条件头以避免并发覆盖。它是标准 HTTP 状态码,适合用于强制客户端使用 If-Match、ETag 或类似乐观锁机制。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 409, 412 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 428 是什么意思”、“428 Precondition Required 怎么解决”或“接口返回 428 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 6585,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 强制客户端使用 If-Match、ETag 或类似乐观锁机制。
  • 客户端或调用方需要根据 428 Precondition Required 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 428 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 428 Precondition Required,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 428 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 428 Precondition Required,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 409, 412 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 428 Precondition Required 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把普通字段校验失败写成 428。
  • 不要在不需要并发控制的读取接口返回 428。
  • 不要只返回 428 却不告诉客户端需要哪个条件头。
来源: RFC 6585 相关状态码: 409, 412
429

Too Many Requests

客户端发送请求过多,被服务端限流。

4xx 客户端错误 标准 推荐使用 RFC 6585
详情

429 Too Many Requests 表示:客户端发送请求过多,被服务端限流。它是标准 HTTP 状态码,适合用于接口限流、登录防刷、爬虫限制、短信验证码频率限制。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 403, 503 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 429 是什么意思”、“429 Too Many Requests 怎么解决”或“接口返回 429 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 6585,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 接口限流、登录防刷、爬虫限制、短信验证码频率限制。
  • 客户端或调用方需要根据 429 Too Many Requests 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 429 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 429 Too Many Requests,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 429 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 429 Too Many Requests,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 403, 503 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 429 Too Many Requests 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把服务整体过载都写成 429;系统不可用更接近 503。
  • 不要在可以重试的限流场景里缺少 Retry-After 或限流说明。
  • 不要用 429 掩盖权限封禁。
来源: RFC 6585 相关状态码: 403, 503
430

Request Header Fields Too Large

请求头过大或被安全策略拒绝的非标准变体。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Non-standard platform convention
详情

430 Request Header Fields Too Large 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:请求头过大或被安全策略拒绝的非标准变体。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于某些平台或代理用 430 表示请求头、Cookie 或安全检查问题。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 430 是什么意思”、“430 Request Header Fields Too Large 怎么解决”或“接口返回 430 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Non-standard platform convention,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 某些平台或代理用 430 表示请求头、Cookie 或安全检查问题。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 430 Request Header Fields Too Large,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 430 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 430 是否由 Non-standard platform convention 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 431, 494,并在响应体里保留更细的内部错误码。
  • 排查 430 Request Header Fields Too Large 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在新系统中优先使用 430;请求头过大更常见的是 431。
  • 不要把请求体过大写成 430。
  • 不要忽略 Cookie 或 Authorization 头膨胀。
来源: Non-standard platform convention 相关状态码: 400, 431, 494
431

Request Header Fields Too Large

请求头字段过大,服务器拒绝处理。

4xx 客户端错误 标准 推荐使用 RFC 6585
详情

431 Request Header Fields Too Large 表示:请求头字段过大,服务器拒绝处理。它是标准 HTTP 状态码,适合用于Cookie 过大、请求头过多、单个 Header 字段超过限制。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 414, 494 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 431 是什么意思”、“431 Request Header Fields Too Large 怎么解决”或“接口返回 431 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 6585,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • Cookie 过大、请求头过多、单个 Header 字段超过限制。
  • 客户端或调用方需要根据 431 Request Header Fields Too Large 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 431 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 431 Request Header Fields Too Large,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 431 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 431 Request Header Fields Too Large,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 414, 494 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 431 Request Header Fields Too Large 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把请求体过大写成 431。
  • 不要让前端长期堆积无用 Cookie。
  • 不要只提示 Bad Request 却不指出 Header 过大。
来源: RFC 6585 相关状态码: 400, 414, 494
440

Login Time-out

登录会话超时,客户端需要重新认证。

4xx 客户端错误 非标准 谨慎使用 Microsoft IIS
详情

440 Login Time-out 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:登录会话超时,客户端需要重新认证。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Microsoft IIS、Exchange 或企业系统中会话过期后要求重新登录。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 440 是什么意思”、“440 Login Time-out 怎么解决”或“接口返回 440 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Microsoft IIS 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Microsoft IIS、Exchange 或企业系统中会话过期后要求重新登录。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 440 Login Time-out,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 440 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 440 是否由 Microsoft IIS 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 401, 403, 419,并在响应体里保留更细的内部错误码。
  • 排查 440 Login Time-out 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 440 当作标准 HTTP 认证语义。
  • 开放 API 更推荐使用 401。
  • 不要只提示超时而不引导用户重新登录。
来源: Microsoft IIS 相关状态码: 401, 403, 419
444

No Response

Nginx 主动关闭连接,不向客户端返回响应。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Nginx
详情

444 No Response 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Nginx 主动关闭连接,不向客户端返回响应。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Nginx 拦截恶意请求、空主机名、扫描流量或需要静默丢弃的连接。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 444 是什么意思”、“444 No Response 怎么解决”或“接口返回 444 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Nginx 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Nginx 拦截恶意请求、空主机名、扫描流量或需要静默丢弃的连接。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 444 No Response,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 444 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 444 是否由 Nginx 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 403, 499,并在响应体里保留更细的内部错误码。
  • 排查 444 No Response 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在应用层 API 中返回 444。
  • 不要把 444 当作源站业务错误。
  • 不要误伤健康检查、搜索引擎爬虫或正常用户。
来源: Nginx 相关状态码: 400, 403, 499
449

Retry With

请求需要补充信息后重试。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Microsoft IIS
详情

449 Retry With 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:请求需要补充信息后重试。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Microsoft 扩展,历史上用于提示客户端带上额外参数或执行重试。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 449 是什么意思”、“449 Retry With 怎么解决”或“接口返回 449 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Microsoft IIS 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Microsoft 扩展,历史上用于提示客户端带上额外参数或执行重试。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 449 Retry With,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 449 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 449 是否由 Microsoft IIS 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 401, 428,并在响应体里保留更细的内部错误码。
  • 排查 449 Retry With 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在新 API 中使用 449。
  • 不要让调用方猜测需要补充什么信息。
  • 缺少参数、未认证或缺少条件头时,应优先选择标准状态码。
来源: Microsoft IIS 相关状态码: 400, 401, 428
450

Blocked by Windows Parental Controls

请求被 Windows 家长控制或类似策略阻止。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Microsoft IIS
详情

450 Blocked by Windows Parental Controls 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:请求被 Windows 家长控制或类似策略阻止。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于历史 Microsoft 扩展,用于表示本地策略阻止访问。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 450 是什么意思”、“450 Blocked by Windows Parental Controls 怎么解决”或“接口返回 450 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Microsoft IIS 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 历史 Microsoft 扩展,用于表示本地策略阻止访问。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 450 Blocked by Windows Parental Controls,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 450 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 450 是否由 Microsoft IIS 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 403, 451,并在响应体里保留更细的内部错误码。
  • 排查 450 Blocked by Windows Parental Controls 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把普通法律屏蔽写成 450;法律原因更适合 451。
  • 不要在现代 API 中使用 450。
  • 不要把它当成服务端业务错误。
来源: Microsoft IIS 相关状态码: 403, 451
451

Unavailable For Legal Reasons

资源因法律原因不可用。

4xx 客户端错误 标准 谨慎使用 RFC 7725
详情

451 Unavailable For Legal Reasons 表示:资源因法律原因不可用。它是标准 HTTP 状态码,适合用于版权限制、法院命令、地区合规、监管要求屏蔽内容。。理解这个状态码时,关键不是只看数字属于 4xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 403, 404, 410 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 451 是什么意思”、“451 Unavailable For Legal Reasons 怎么解决”或“接口返回 451 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 RFC 7725,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 版权限制、法院命令、地区合规、监管要求屏蔽内容。
  • 客户端或调用方需要根据 451 Unavailable For Legal Reasons 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 451 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 451 Unavailable For Legal Reasons,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 451 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 451 Unavailable For Legal Reasons,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 403, 404, 410 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 451 Unavailable For Legal Reasons 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把普通权限不足写成 451。
  • 不要用 451 掩盖技术故障。
  • 不要在没有法律或监管原因时使用 451。
来源: RFC 7725 相关状态码: 403, 404, 410
460

Client Closed Connection

客户端在负载均衡器响应前关闭连接。

4xx 客户端错误 非标准 不建议作为公共 API 契约 AWS Elastic Load Balancing
详情

460 Client Closed Connection 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:客户端在负载均衡器响应前关闭连接。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于AWS Elastic Load Balancing 日志中用于表示客户端提前断开。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 460 是什么意思”、“460 Client Closed Connection 怎么解决”或“接口返回 460 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 AWS Elastic Load Balancing,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • AWS Elastic Load Balancing 日志中用于表示客户端提前断开。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 460 Client Closed Connection,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 460 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 460 是否由 AWS Elastic Load Balancing 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 408, 499, 504,并在响应体里保留更细的内部错误码。
  • 排查 460 Client Closed Connection 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 460 当作源站应用主动返回的错误。
  • 不要只查应用日志而忽略 ALB 日志。
  • 不要忽视客户端超时设置和移动网络中断。
来源: AWS Elastic Load Balancing 相关状态码: 408, 499, 504
463

Too Many IP Addresses

请求中的 X-Forwarded-For 等头部包含过多 IP 地址。

4xx 客户端错误 非标准 不建议作为公共 API 契约 AWS Elastic Load Balancing
详情

463 Too Many IP Addresses 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:请求中的 X-Forwarded-For 等头部包含过多 IP 地址。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于AWS ALB 等网关在转发链路头部异常时记录或返回。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 463 是什么意思”、“463 Too Many IP Addresses 怎么解决”或“接口返回 463 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 AWS Elastic Load Balancing,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • AWS ALB 等网关在转发链路头部异常时记录或返回。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 463 Too Many IP Addresses,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 463 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 463 是否由 AWS Elastic Load Balancing 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 431, 494,并在响应体里保留更细的内部错误码。
  • 排查 463 Too Many IP Addresses 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 463 当作普通参数错误。
  • 不要忽略 X-Forwarded-For 过长或被污染的问题。
  • 不要只排查后端代码,应检查代理链路。
来源: AWS Elastic Load Balancing 相关状态码: 400, 431, 494
464

Incompatible Protocols

客户端与目标组之间协议不兼容。

4xx 客户端错误 非标准 不建议作为公共 API 契约 AWS Elastic Load Balancing
详情

464 Incompatible Protocols 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:客户端与目标组之间协议不兼容。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于AWS ALB 在 HTTP/1、HTTP/2、gRPC 或目标组协议不匹配时使用。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 464 是什么意思”、“464 Incompatible Protocols 怎么解决”或“接口返回 464 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 AWS Elastic Load Balancing,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • AWS ALB 在 HTTP/1、HTTP/2、gRPC 或目标组协议不匹配时使用。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 464 Incompatible Protocols,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 464 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 464 是否由 AWS Elastic Load Balancing 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 426, 502,并在响应体里保留更细的内部错误码。
  • 排查 464 Incompatible Protocols 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 464 误判成源站 500。
  • 不要只改应用代码而不检查 ALB 协议配置。
  • 不要忽略 gRPC、HTTP/2 和目标组协议版本是否匹配。
来源: AWS Elastic Load Balancing 相关状态码: 400, 426, 502
494

Request Header Too Large

Nginx 判断请求头过大。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Nginx
详情

494 Request Header Too Large 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Nginx 判断请求头过大。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Nginx 中 Cookie、Header 或请求行超过配置限制。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 494 是什么意思”、“494 Request Header Too Large 怎么解决”或“接口返回 494 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Nginx 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Nginx 中 Cookie、Header 或请求行超过配置限制。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 494 Request Header Too Large,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 494 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 494 是否由 Nginx 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 414, 431,并在响应体里保留更细的内部错误码。
  • 排查 494 Request Header Too Large 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把请求体过大写成 494。
  • 不要和标准 431 混淆;494 是 Nginx 实现扩展。
  • 不要长期保留膨胀 Cookie 而只调大 Nginx 限制。
来源: Nginx 相关状态码: 400, 414, 431
495

SSL Certificate Error

Nginx 校验客户端证书时发生错误。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Nginx
详情

495 SSL Certificate Error 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Nginx 校验客户端证书时发生错误。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于双向 TLS、客户端证书错误、证书链无法验证。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 495 是什么意思”、“495 SSL Certificate Error 怎么解决”或“接口返回 495 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Nginx 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 双向 TLS、客户端证书错误、证书链无法验证。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 495 SSL Certificate Error,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 495 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 495 是否由 Nginx 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 401, 403,并在响应体里保留更细的内部错误码。
  • 排查 495 SSL Certificate Error 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把普通登录失败写成 495。
  • 不要和 Cloudflare 526 混淆。
  • 不要在非 mTLS 场景中使用 495。
来源: Nginx 相关状态码: 400, 401, 403, 496, 526
496

SSL Certificate Required

Nginx 要求客户端证书,但请求没有提供。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Nginx
详情

496 SSL Certificate Required 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Nginx 要求客户端证书,但请求没有提供。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于mTLS 场景缺少客户端证书。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 496 是什么意思”、“496 SSL Certificate Required 怎么解决”或“接口返回 496 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Nginx 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • mTLS 场景缺少客户端证书。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 496 SSL Certificate Required,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 496 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 496 是否由 Nginx 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 401, 403, 495,并在响应体里保留更细的内部错误码。
  • 排查 496 SSL Certificate Required 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 Token 缺失写成 496。
  • 不要在非 mTLS 场景中使用 496。
  • 不要只提示证书缺失而不说明客户端需要安装或选择证书。
来源: Nginx 相关状态码: 401, 403, 495
497

HTTP Request Sent to HTTPS Port

客户端把普通 HTTP 请求发到了 HTTPS 端口。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Nginx
详情

497 HTTP Request Sent to HTTPS Port 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:客户端把普通 HTTP 请求发到了 HTTPS 端口。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于用户或代理用 http:// 访问只接受 TLS 的端口。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 497 是什么意思”、“497 HTTP Request Sent to HTTPS Port 怎么解决”或“接口返回 497 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Nginx 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 用户或代理用 http:// 访问只接受 TLS 的端口。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 497 HTTP Request Sent to HTTPS Port,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 497 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 497 是否由 Nginx 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 400, 426, 301,并在响应体里保留更细的内部错误码。
  • 排查 497 HTTP Request Sent to HTTPS Port 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 497 当作应用业务错误。
  • 不要在后端业务代码中模拟 497。
  • 不要忽略负载均衡和 TLS 终止层的协议配置。
来源: Nginx 相关状态码: 400, 426, 301
498

Invalid Token

Token 无效或已过期的非标准状态码。

4xx 客户端错误 非标准 谨慎使用 Esri ArcGIS
详情

498 Invalid Token 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Token 无效或已过期的非标准状态码。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于ArcGIS、部分 API 网关或自定义认证系统中表示令牌不可用。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 498 是什么意思”、“498 Invalid Token 怎么解决”或“接口返回 498 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Esri ArcGIS,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • ArcGIS、部分 API 网关或自定义认证系统中表示令牌不可用。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 498 Invalid Token,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 498 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 498 是否由 Esri ArcGIS 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 401, 403, 419,并在响应体里保留更细的内部错误码。
  • 排查 498 Invalid Token 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 开放 API 更推荐使用 401 或 403。
  • 不要把所有字段校验失败写成 498。
  • 不要只返回 Token 无效而不说明是否过期、签名错误或权限不足。
来源: Esri ArcGIS 相关状态码: 401, 403, 419
499

Client Closed Request

客户端在服务器响应前主动关闭连接。

4xx 客户端错误 非标准 不建议作为公共 API 契约 Nginx
详情

499 Client Closed Request 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:客户端在服务器响应前主动关闭连接。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Nginx 访问日志中常见,通常表示浏览器取消、前端超时、用户关闭页面或网络断开。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 499 是什么意思”、“499 Client Closed Request 怎么解决”或“接口返回 499 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。客户端侧错误响应,重点是请求格式、身份认证、权限、资源状态、业务校验和调用方下一步修正方式。它来自 Nginx 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Nginx 访问日志中常见,通常表示浏览器取消、前端超时、用户关闭页面或网络断开。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 499 Client Closed Request,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 499 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 调用方请求存在格式、身份、权限、资源状态或业务校验问题,需要修改请求后再重试。
  • 前端需要把错误展示给用户,例如重新登录、补全字段、降低请求频率、检查文件大小或确认操作冲突。
排查建议
  • 先确认 499 是否由 Nginx 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 408, 460, 504,并在响应体里保留更细的内部错误码。
  • 排查 499 Client Closed Request 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 499 当作服务器主动失败。
  • 不要只查后端错误日志,应用可能根本没有异常。
  • 不要忽视前端取消请求、客户端超时和用户关闭页面。
来源: Nginx 相关状态码: 408, 460, 504

5xx 服务端错误

服务端或网关侧问题,可能来自应用异常、上游依赖、代理、CDN、DNS、TLS、过载、维护或超时。

500

Internal Server Error

服务器内部发生未知错误,无法完成请求。

5xx 服务端错误 标准 推荐使用 RFC 9110
详情

500 Internal Server Error 表示:服务器内部发生未知错误,无法完成请求。它是标准 HTTP 状态码,适合用于代码异常、未捕获错误、模板渲染失败、后端服务异常。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 502, 503, 504 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 500 是什么意思”、“500 Internal Server Error 怎么解决”或“接口返回 500 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 代码异常、未捕获错误、模板渲染失败、后端服务异常。
  • 客户端或调用方需要根据 500 Internal Server Error 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 500 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 500 Internal Server Error,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 500 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 500 Internal Server Error,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 502, 503, 504 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 500 Internal Server Error 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把客户端参数错误写成 500。
  • 不要在生产响应中暴露堆栈、数据库连接串或环境变量。
  • 不要长期用 500 兜底所有可预期错误。
来源: RFC 9110 相关状态码: 502, 503, 504
501

Not Implemented

服务器不支持完成请求所需的功能。

5xx 服务端错误 标准 推荐使用 RFC 9110
详情

501 Not Implemented 表示:服务器不支持完成请求所需的功能。它是标准 HTTP 状态码,适合用于不支持某个 HTTP 方法、协议特性或接口能力尚未实现。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 405, 426, 505 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 501 是什么意思”、“501 Not Implemented 怎么解决”或“接口返回 501 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。

常见场景
  • 不支持某个 HTTP 方法、协议特性或接口能力尚未实现。
  • 客户端或调用方需要根据 501 Not Implemented 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 501 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 501 Not Implemented,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 501 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 501 Not Implemented,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 405, 426, 505 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 501 Not Implemented 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把业务功能暂未开放简单写成 501。
  • 不要把未授权或权限不足写成 501。
  • 如果只是某个资源不支持方法,405 更准确。
来源: RFC 9110 相关状态码: 405, 426, 505
502

Bad Gateway

网关或代理从上游服务器收到无效响应。

5xx 服务端错误 标准 推荐使用 RFC 9110
详情

502 Bad Gateway 表示:网关或代理从上游服务器收到无效响应。它是标准 HTTP 状态码,适合用于反向代理、API 网关、负载均衡连接上游时收到错误响应。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 500, 503, 504 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 502 是什么意思”、“502 Bad Gateway 怎么解决”或“接口返回 502 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 反向代理、API 网关、负载均衡连接上游时收到错误响应。
  • 客户端或调用方需要根据 502 Bad Gateway 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 502 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 502 Bad Gateway,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 502 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 502 Bad Gateway,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 500, 503, 504, 521 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 502 Bad Gateway 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把应用内部异常都写成 502。
  • 不要把上游超时写成 502;等待超时更接近 504。
  • 不要只看浏览器错误页,应查网关和源站日志。
来源: RFC 9110 相关状态码: 500, 503, 504, 521, 522
503

Service Unavailable

服务暂时不可用,通常是过载或维护中。

5xx 服务端错误 标准 推荐使用 RFC 9110
详情

503 Service Unavailable 表示:服务暂时不可用,通常是过载或维护中。它是标准 HTTP 状态码,适合用于服务维护、容量不足、限流保护、依赖服务临时不可用。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 500, 502, 504 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 503 是什么意思”、“503 Service Unavailable 怎么解决”或“接口返回 503 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 服务维护、容量不足、限流保护、依赖服务临时不可用。
  • 客户端或调用方需要根据 503 Service Unavailable 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 503 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 503 Service Unavailable,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 503 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 503 Service Unavailable,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 500, 502, 504, 429 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 503 Service Unavailable 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把永久下线资源写成 503。
  • 不要把用户个人限流写成 503;限流更接近 429。
  • 不要长期返回 503 却没有恢复策略。
来源: RFC 9110 相关状态码: 500, 502, 504, 429
504

Gateway Timeout

网关或代理等待上游响应超时。

5xx 服务端错误 标准 推荐使用 RFC 9110
详情

504 Gateway Timeout 表示:网关或代理等待上游响应超时。它是标准 HTTP 状态码,适合用于上游接口慢、数据库查询慢、服务链路阻塞、代理超时。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 408, 502, 503 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 504 是什么意思”、“504 Gateway Timeout 怎么解决”或“接口返回 504 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 REST API 或 JSON API 可以使用它,但仍建议配合结构化响应体说明具体原因。这些常见状态码也最容易被滥用,建议在响应体中补充业务错误码、字段级错误、traceId、重试建议或帮助文档链接,这样既方便开发者排查,也有利于搜索引擎理解页面的独特内容。

常见场景
  • 上游接口慢、数据库查询慢、服务链路阻塞、代理超时。
  • 客户端或调用方需要根据 504 Gateway Timeout 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 504 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 504 Gateway Timeout,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 504 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 504 Gateway Timeout,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 408, 502, 503, 524 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 504 Gateway Timeout 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把客户端上传慢写成 504;客户端请求超时更接近 408。
  • 不要把上游返回无效响应写成 504;那更接近 502。
  • 不要只延长超时时间而不优化慢请求。
来源: RFC 9110 相关状态码: 408, 502, 503, 524
505

HTTP Version Not Supported

服务器不支持请求使用的 HTTP 版本。

5xx 服务端错误 标准 谨慎使用 RFC 9110
详情

505 HTTP Version Not Supported 表示:服务器不支持请求使用的 HTTP 版本。它是标准 HTTP 状态码,适合用于客户端使用了服务端不支持的 HTTP/1.0、HTTP/2 或其他版本。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 426, 501 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 505 是什么意思”、“505 HTTP Version Not Supported 怎么解决”或“接口返回 505 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 9110,属于可移植的标准 HTTP 语义,适合在接口文档、错误页、SDK 和监控系统中直接说明。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • 客户端使用了服务端不支持的 HTTP/1.0、HTTP/2 或其他版本。
  • 客户端或调用方需要根据 505 HTTP Version Not Supported 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 505 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 505 HTTP Version Not Supported,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 505 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 505 HTTP Version Not Supported,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 426, 501 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 505 HTTP Version Not Supported 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 505 表示业务 API 版本不支持。
  • 不要把 TLS 握手问题写成 505。
  • 不要在服务端其实支持该 HTTP 版本时返回 505。
来源: RFC 9110 相关状态码: 400, 426, 501
506

Variant Also Negotiates

服务器内容协商配置错误,变体资源自身也参与协商。

5xx 服务端错误 标准 不建议作为公共 API 契约 RFC 2295
详情

506 Variant Also Negotiates 表示:服务器内容协商配置错误,变体资源自身也参与协商。它是扩展状态码,适合用于透明内容协商配置循环或服务器错误配置。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 300, 500 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 506 是什么意思”、“506 Variant Also Negotiates 怎么解决”或“接口返回 506 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 2295,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 透明内容协商配置循环或服务器错误配置。
  • 客户端或调用方需要根据 506 Variant Also Negotiates 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 506 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 506 Variant Also Negotiates,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 506 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 506 Variant Also Negotiates,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 300, 500 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 506 Variant Also Negotiates 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把客户端 Accept 错误写成 506;那更接近 406。
  • 不要用 506 表示业务规则失败。
  • 普通 API 基本不需要主动返回 506。
来源: RFC 2295 相关状态码: 300, 500
507

Insufficient Storage

服务器没有足够存储空间完成请求。

5xx 服务端错误 标准 谨慎使用 RFC 4918
详情

507 Insufficient Storage 表示:服务器没有足够存储空间完成请求。它是扩展状态码,适合用于WebDAV 上传、文件写入、磁盘空间不足、配额不足。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 413, 423, 500 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 507 是什么意思”、“507 Insufficient Storage 怎么解决”或“接口返回 507 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 4918,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通 API 可以在语义非常明确时使用它,但需要在文档中写清楚触发条件和客户端处理方式。

常见场景
  • WebDAV 上传、文件写入、磁盘空间不足、配额不足。
  • 客户端或调用方需要根据 507 Insufficient Storage 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 507 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 507 Insufficient Storage,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 507 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 507 Insufficient Storage,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 413, 423, 500 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 507 Insufficient Storage 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把所有写入失败都写成 507。
  • 不要用 507 表示数据库普通错误。
  • 不要在没有存储或配额语义时使用 507。
来源: RFC 4918 相关状态码: 413, 423, 500
508

Loop Detected

服务器在处理请求时检测到无限循环。

5xx 服务端错误 标准 不建议作为公共 API 契约 RFC 5842
详情

508 Loop Detected 表示:服务器在处理请求时检测到无限循环。它是扩展状态码,适合用于WebDAV 绑定循环、递归目录遍历、资源引用环。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 207, 208, 500 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 508 是什么意思”、“508 Loop Detected 怎么解决”或“接口返回 508 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 5842,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • WebDAV 绑定循环、递归目录遍历、资源引用环。
  • 客户端或调用方需要根据 508 Loop Detected 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 508 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 508 Loop Detected,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 508 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 508 Loop Detected,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 207, 208, 500 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 508 Loop Detected 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把代码死循环都写成 508;应用异常通常是 500。
  • 不要在没有资源引用循环时使用 508。
  • 普通 API 基本不需要 508。
来源: RFC 5842 相关状态码: 207, 208, 500
509

Bandwidth Limit Exceeded

站点或账户带宽额度已超限。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Apache/cPanel
详情

509 Bandwidth Limit Exceeded 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:站点或账户带宽额度已超限。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于部分 Apache/cPanel/托管平台用于表示流量配额耗尽。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 509 是什么意思”、“509 Bandwidth Limit Exceeded 怎么解决”或“接口返回 509 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Apache/cPanel 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 部分 Apache/cPanel/托管平台用于表示流量配额耗尽。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 509 Bandwidth Limit Exceeded,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 509 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 509 是否由 Apache/cPanel 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 429, 503, 507,并在响应体里保留更细的内部错误码。
  • 排查 509 Bandwidth Limit Exceeded 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 509 当作标准状态码。
  • 普通限流应使用 429。
  • 不要只扩容应用,应检查带宽配额、爬虫和静态资源流量。
来源: Apache/cPanel 相关状态码: 429, 503, 507
510

Not Extended

请求缺少服务器要求的扩展信息;该状态码已经过时。

5xx 服务端错误 已废弃 不建议作为公共 API 契约 RFC 2774
详情

510 Not Extended 表示:请求缺少服务器要求的扩展信息;该状态码已经过时。它是扩展状态码,适合用于历史 HTTP 扩展机制,现代 API 基本不使用。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 400, 501 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 510 是什么意思”、“510 Not Extended 怎么解决”或“接口返回 510 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 2774,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 历史 HTTP 扩展机制,现代 API 基本不使用。
  • 客户端或调用方需要根据 510 Not Extended 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 510 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 510 Not Extended,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 510 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 510 Not Extended,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 400, 501 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 510 Not Extended 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要在新系统中使用 510。
  • 不要把普通缺少参数写成 510。
  • 不要把未实现功能写成 510;通常 501 更清楚。
来源: RFC 2774 相关状态码: 400, 501
511

Network Authentication Required

客户端需要先通过网络认证才能访问。

5xx 服务端错误 标准 不建议作为公共 API 契约 RFC 6585
详情

511 Network Authentication Required 表示:客户端需要先通过网络认证才能访问。它是扩展状态码,适合用于公共 Wi-Fi 门户、企业网络认证、强制登录网关。。理解这个状态码时,关键不是只看数字属于 5xx,而是要判断请求是否已经被服务器理解、当前资源状态是否允许操作、客户端后续是否还需要采取动作。对于普通业务 API,应该把它和 401, 407, 403 等相关状态码区分开,避免把语法错误、权限问题、资源状态冲突、代理错误或缓存命中混在一起。换句话说,当用户搜索“HTTP 511 是什么意思”、“511 Network Authentication Required 怎么解决”或“接口返回 511 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 RFC 6585,不是所有普通业务接口都应该主动使用;使用时要说明扩展来源、客户端兼容性和与核心 HTTP 状态码的边界。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。

常见场景
  • 公共 Wi-Fi 门户、企业网络认证、强制登录网关。
  • 客户端或调用方需要根据 511 Network Authentication Required 明确判断下一步行为,而不是只把它当作普通成功或失败。
  • 需要在接口文档、日志分析、监控告警或错误页中准确解释 511 的含义。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 511 Network Authentication Required,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 511 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
排查建议
  • 如果收到 511 Network Authentication Required,先确认它是否符合当前请求方法、资源状态和业务语义。
  • 检查请求头、请求体、认证信息、缓存条件、代理链路和服务端日志,找到触发该状态码的直接原因。
  • 如果这个状态码容易与 401, 407, 403 混淆,应在接口响应体中返回清晰的错误码、字段级错误或下一步操作建议。
  • 排查 511 Network Authentication Required 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要用 511 表示网站登录失败。
  • 不要用 511 表示代理认证;代理认证是 407。
  • 不要在源站业务接口中滥用 511。
来源: RFC 6585 相关状态码: 401, 407, 403
520

Web Server Returned an Unknown Error

Cloudflare 从源站收到空白、未知或异常响应。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

520 Web Server Returned an Unknown Error 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 从源站收到空白、未知或异常响应。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Cloudflare 代理站点时,源站返回了 Cloudflare 无法归类的异常响应。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 520 是什么意思”、“520 Web Server Returned an Unknown Error 怎么解决”或“接口返回 520 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Cloudflare 代理站点时,源站返回了 Cloudflare 无法归类的异常响应。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 520 Web Server Returned an Unknown Error,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 520 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 520 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 500, 502, 521,并在响应体里保留更细的内部错误码。
  • 排查 520 Web Server Returned an Unknown Error 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 520 当作标准 500。
  • 不要只看 Cloudflare 错误页,应结合 Ray ID 和源站日志。
  • 不要忽略源站空响应、异常响应头和连接提前关闭。
来源: Cloudflare 相关状态码: 500, 502, 521, 522
521

Web Server Is Down

Cloudflare 无法连接源站,源站拒绝连接或 Web 服务不可用。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

521 Web Server Is Down 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 无法连接源站,源站拒绝连接或 Web 服务不可用。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于源站 Web 服务离线、防火墙拒绝 Cloudflare IP、端口未监听。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 521 是什么意思”、“521 Web Server Is Down 怎么解决”或“接口返回 521 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 源站 Web 服务离线、防火墙拒绝 Cloudflare IP、端口未监听。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 521 Web Server Is Down,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 521 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 521 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 502, 503, 522,并在响应体里保留更细的内部错误码。
  • 排查 521 Web Server Is Down 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 521 当作 DNS 问题。
  • 不要只重启应用而不检查端口、防火墙和 Cloudflare IP 放行。
  • 不要忽略源站服务是否真的在监听 80/443。
来源: Cloudflare 相关状态码: 502, 503, 522, 523
522

Connection Timed Out

Cloudflare 连接源站超时。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

522 Connection Timed Out 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 连接源站超时。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Cloudflare 到源站 TCP 连接或请求确认超时,常见于防火墙、网络丢包或源站过载。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 522 是什么意思”、“522 Connection Timed Out 怎么解决”或“接口返回 522 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Cloudflare 到源站 TCP 连接或请求确认超时,常见于防火墙、网络丢包或源站过载。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 522 Connection Timed Out,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 522 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 522 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 502, 504, 521,并在响应体里保留更细的内部错误码。
  • 排查 522 Connection Timed Out 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要和 524 混淆;522 是连接阶段超时。
  • 不要只查应用日志,连接没建立时应用可能没有记录。
  • 不要忽略防火墙丢包、安全组和源站过载。
来源: Cloudflare 相关状态码: 502, 504, 521, 524
523

Origin Is Unreachable

Cloudflare 无法到达源站网络。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

523 Origin Is Unreachable 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 无法到达源站网络。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于DNS 指向错误、路由不可达、源站 IP 无法从 Cloudflare 网络访问。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 523 是什么意思”、“523 Origin Is Unreachable 怎么解决”或“接口返回 523 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • DNS 指向错误、路由不可达、源站 IP 无法从 Cloudflare 网络访问。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 523 Origin Is Unreachable,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 523 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 523 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 502, 521, 522,并在响应体里保留更细的内部错误码。
  • 排查 523 Origin Is Unreachable 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 523 当作应用代码错误。
  • 不要和 530 混淆;530 更偏源站主机名解析问题。
  • 不要忽略 DNS 指向和公网路由可达性。
来源: Cloudflare 相关状态码: 502, 521, 522, 530
524

A Timeout Occurred

Cloudflare 已连接源站,但源站没有及时返回 HTTP 响应。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

524 A Timeout Occurred 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 已连接源站,但源站没有及时返回 HTTP 响应。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于长查询、慢接口、大导出、源站处理过久或默认代理读取超时。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 524 是什么意思”、“524 A Timeout Occurred 怎么解决”或“接口返回 524 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 长查询、慢接口、大导出、源站处理过久或默认代理读取超时。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 524 A Timeout Occurred,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 524 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 524 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 504, 522, 503,并在响应体里保留更细的内部错误码。
  • 排查 524 A Timeout Occurred 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要和 522 混淆;524 说明 Cloudflare 已经连上源站。
  • 不要只延长超时而不优化慢接口。
  • 长任务不要同步阻塞,考虑 202 异步处理。
来源: Cloudflare 相关状态码: 504, 522, 503
525

SSL Handshake Failed

Cloudflare 与源站之间 SSL/TLS 握手失败。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

525 SSL Handshake Failed 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 与源站之间 SSL/TLS 握手失败。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于源站 TLS 配置错误、证书链问题、SNI 或加密套件不匹配。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 525 是什么意思”、“525 SSL Handshake Failed 怎么解决”或“接口返回 525 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 源站 TLS 配置错误、证书链问题、SNI 或加密套件不匹配。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 525 SSL Handshake Failed,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 525 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 525 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 502, 526, 495,并在响应体里保留更细的内部错误码。
  • 排查 525 SSL Handshake Failed 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 525 当作浏览器到 Cloudflare 的证书错误。
  • 不要和 526 混淆;526 是证书验证失败。
  • 不要忽略 SNI、TLS 版本和加密套件。
来源: Cloudflare 相关状态码: 502, 526, 495
526

Invalid SSL Certificate

Cloudflare 无法验证源站证书。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

526 Invalid SSL Certificate 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 无法验证源站证书。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Full Strict 模式下源站证书过期、自签名、域名不匹配或证书链无效。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 526 是什么意思”、“526 Invalid SSL Certificate 怎么解决”或“接口返回 526 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Full Strict 模式下源站证书过期、自签名、域名不匹配或证书链无效。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 526 Invalid SSL Certificate,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 526 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 526 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 525, 495, 403,并在响应体里保留更细的内部错误码。
  • 排查 526 Invalid SSL Certificate 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 526 当作用户浏览器证书错误。
  • 不要为绕过问题长期降低 TLS 安全模式。
  • 不要使用过期、自签名或域名不匹配的源站证书。
来源: Cloudflare 相关状态码: 525, 495, 403
527

Railgun Error

Cloudflare Railgun 到源站发生连接或协议错误。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

527 Railgun Error 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare Railgun 到源站发生连接或协议错误。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于使用 Cloudflare Railgun 的站点中,Railgun Listener 与源站连接失败。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 527 是什么意思”、“527 Railgun Error 怎么解决”或“接口返回 527 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 使用 Cloudflare Railgun 的站点中,Railgun Listener 与源站连接失败。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 527 Railgun Error,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 527 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 527 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 502, 523, 524,并在响应体里保留更细的内部错误码。
  • 排查 527 Railgun Error 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 527 当作普通源站 500。
  • 不使用 Railgun 的站点通常不应该出现 527。
  • 不要忽略 Railgun Listener 和源站连接配置。
来源: Cloudflare 相关状态码: 502, 523, 524
530

Origin DNS Error

Cloudflare 无法解析源站主机名或遇到源站 DNS 问题。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Cloudflare
详情

530 Origin DNS Error 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:Cloudflare 无法解析源站主机名或遇到源站 DNS 问题。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于Cloudflare 代理域名时,源站主机名无法解析,响应体通常还会包含 Cloudflare 1xxx 错误码。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 530 是什么意思”、“530 Origin DNS Error 怎么解决”或“接口返回 530 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Cloudflare,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • Cloudflare 代理域名时,源站主机名无法解析,响应体通常还会包含 Cloudflare 1xxx 错误码。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 530 Origin DNS Error,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 530 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 530 是否由 Cloudflare 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 523, 521, 522,并在响应体里保留更细的内部错误码。
  • 排查 530 Origin DNS Error 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 530 当作标准 HTTP 语义。
  • 不要和 523 混淆;523 更偏网络不可达。
  • 不要忽略 Cloudflare 响应体中的 1xxx 错误码。
来源: Cloudflare 相关状态码: 523, 521, 522
561

Unauthorized

AWS 负载均衡认证失败或身份验证相关错误。

5xx 服务端错误 非标准 不建议作为公共 API 契约 AWS Elastic Load Balancing
详情

561 Unauthorized 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:AWS 负载均衡认证失败或身份验证相关错误。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于AWS ALB 开启用户认证时,身份提供方、令牌或认证流程异常。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 561 是什么意思”、“561 Unauthorized 怎么解决”或“接口返回 561 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 AWS Elastic Load Balancing,通常由厂商平台、CDN、负载均衡或托管服务生成;排查时不能只看应用代码,还要看该平台的日志和配置。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • AWS ALB 开启用户认证时,身份提供方、令牌或认证流程异常。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 561 Unauthorized,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 561 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 561 是否由 AWS Elastic Load Balancing 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 401, 403, 511,并在响应体里保留更细的内部错误码。
  • 排查 561 Unauthorized 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 561 当作标准 401。
  • 不要只查应用代码,认证可能在 ALB 层已经失败。
  • 不要忽略 IdP、回调地址和 ALB 认证配置。
来源: AWS Elastic Load Balancing 相关状态码: 401, 403, 511
598

Network Read Timeout Error

代理或客户端读取上游响应超时。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Proxy / Gateway convention
详情

598 Network Read Timeout Error 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:代理或客户端读取上游响应超时。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于部分代理、客户端库或网关用来表示已连接但读取响应超时。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 598 是什么意思”、“598 Network Read Timeout Error 怎么解决”或“接口返回 598 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Proxy / Gateway convention 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 部分代理、客户端库或网关用来表示已连接但读取响应超时。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 598 Network Read Timeout Error,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 598 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 598 是否由 Proxy / Gateway convention 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 504, 524, 599,并在响应体里保留更细的内部错误码。
  • 排查 598 Network Read Timeout Error 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 598 当作 IANA 标准码。
  • 不要和 599 混淆;599 更偏连接阶段超时。
  • 不要只延长读取超时而不优化上游响应。
来源: Proxy / Gateway convention 相关状态码: 504, 524, 599
599

Network Connect Timeout Error

代理或客户端连接上游超时。

5xx 服务端错误 非标准 不建议作为公共 API 契约 Proxy / Gateway convention
详情

599 Network Connect Timeout Error 不是 IANA 注册的标准 HTTP 状态码,而是来自特定厂商、服务器实现、框架或代理链路的非标准状态码。它通常表示:代理或客户端连接上游超时。使用它时要特别注意来源,因为浏览器、HTTP 客户端、监控系统和中间代理不一定都把它当作通用 HTTP 语义处理。它适合用于部分代理、客户端库或网关用来表示连接阶段超时。,但不建议普通业务 API 把它当作可移植的公共响应契约。换句话说,当用户搜索“HTTP 599 是什么意思”、“599 Network Connect Timeout Error 怎么解决”或“接口返回 599 的原因”时,真正需要知道的不只是标准短语,而是它出现在哪一层、是谁生成的、调用方应该继续等待、重试、重新登录、修改请求,还是联系服务端排查。服务端或网关侧错误响应,重点是区分应用异常、上游异常、维护过载、代理超时、TLS、DNS 和源站连接问题。它来自 Proxy / Gateway convention 的实现约定,常出现在服务器、框架或代理日志里;它对排障很有价值,但不是通用 RFC 状态码。普通业务 API 不建议主动依赖它;如果必须展示,应明确标记来源和适用边界,避免调用方误以为它是通用语义。这类扩展码尤其要注意责任边界:浏览器看到的是一个 HTTP 响应,但生成它的可能是 CDN、Nginx、IIS、AWS ALB、应用网关或框架中间件,而不一定是业务接口本身。

常见场景
  • 部分代理、客户端库或网关用来表示连接阶段超时。
  • 用户、开发者或运维在日志、浏览器开发者工具、接口调试工具、CDN 面板或服务器访问日志中看到 599 Network Connect Timeout Error,需要判断这是标准协议语义、业务响应,还是中间层生成的状态。
  • 编写接口文档、错误码说明、SEO 状态码页面或故障排查手册时,需要解释 599 的含义、常见原因、修复步骤以及容易混淆的相关状态码。
  • 服务端、网关、CDN、负载均衡或上游依赖出现问题,客户端通常无法单靠修改参数解决。
  • 运维需要结合访问日志、错误日志、链路追踪、上游健康检查、DNS、TLS 和超时配置定位故障层级。
排查建议
  • 先确认 599 是否由 Proxy / Gateway convention 或对应中间层生成,再去查源站应用日志、代理日志和访问日志。
  • 检查 DNS、TLS、代理转发、请求头大小、连接超时、客户端取消请求、限流和上游服务状态等链路因素。
  • 如果要对外提供稳定 API,优先把它转换或归类到标准状态码,例如 502, 522, 598,并在响应体里保留更细的内部错误码。
  • 排查 599 Network Connect Timeout Error 时,先确认状态码是谁生成的:浏览器、客户端库、业务应用、反向代理、CDN、负载均衡、API 网关还是上游服务。
  • 查看响应头、响应体、服务器访问日志、错误日志、网关日志和 traceId,避免只凭浏览器错误页判断问题。
  • 把状态码和响应体里的业务错误码结合起来看:HTTP 状态码负责表达协议和资源层语义,业务错误码负责表达更细的产品规则。
不建议用于
  • 不要把 599 当作 IANA 标准码。
  • 不要和 598 或 504 混淆。
  • 不要只查应用日志,应先确认连接是否建立。
来源: Proxy / Gateway convention 相关状态码: 502, 522, 598

这个 HTTP 状态码参考覆盖什么

这个页面不是只罗列数字和英文短语,而是面向日常接口调试和线上排障整理。每个状态码都把协议含义、常见来源、排查方向和 API 设计建议放在一起,方便前端、后端、测试、运维、SEO 和接口文档维护人员共同使用。

  • 标准码与扩展码一起查询

    覆盖常见 RFC 标准状态码,也包含 WebDAV、Nginx、Cloudflare、AWS 负载均衡、Microsoft/IIS、代理网关和可恢复上传草案中经常看到的扩展或非标准状态码。

  • 按排查语境搜索

    搜索范围不仅包括状态码和短语,也覆盖分类、摘要、来源、相关状态码、常见场景、排查建议和不建议使用的情况。搜索“缓存”“超时”“WebSocket”“Cloudflare”“限流”等关键词也能定位到相关条目。

  • 接口设计建议

    每个状态码都标明是否适合公共 REST API 或 JSON API 使用,帮助区分可以写进接口文档的稳定语义,以及更适合作为网关、CDN 或内部日志细节保留的状态。

  • 兼顾运维和 SEO 影响

    重定向、软错误、404/410、429 限流、5xx 故障、CDN 网关错误等都按实际影响说明,方便同时处理用户访问、自动化客户端和搜索引擎抓取问题。

如何使用这个状态码查询工具

你可以在查看浏览器开发者工具、服务器日志、API 响应、CDN 面板、负载均衡日志、搜索引擎抓取报告或监控告警时使用这个页面。

  1. 1

    输入你看到的数字状态码、英文短语、厂商名称或故障现象关键词。

  2. 2

    如果已经知道大类,可以先用 1xx、2xx、3xx、4xx、5xx 过滤结果。

  3. 3

    打开匹配条目后先读摘要,再看常见场景,判断这个状态码最可能由哪一层生成。

  4. 4

    修改接口契约前,对比相关状态码。很多问题来自把 200、400、401、403、404、409、422、429、500、502、503、504 混用。

  5. 5

    根据来源和生命周期判断它是否适合写进公共接口文档,还是只应该作为基础设施或内部日志细节。

每个状态码包含哪些信息

条目结构适合排障时快速阅读,也可以作为接口文档、错误码说明和内部技术手册的参考。

  • 状态码数字、英文短语和所属分类。
  • 用于快速识别的摘要,以及更完整的语义说明。
  • 它在 API、浏览器、CDN、网关、代理和服务端日志中常见的出现位置。
  • 面向客户端请求、后端服务、路由、认证、缓存、重定向和基础设施的排查建议。
  • 不建议使用的场景,避免把状态码用于错误的语义。
  • 相关状态码,方便在改接口或写文档前做对比。
  • 标准、已废弃、临时、厂商扩展和实现约定等生命周期与来源信息。

常见使用场景

只要状态码出现在响应、日志、SEO 报告、可用性告警、接口测试、SDK 错误或反向代理面板中,都可以用这个页面辅助判断。

  • REST API 与 JSON API 设计

    为创建、更新、校验、认证、授权、状态冲突、限流、异步任务和无响应体等接口流程选择更准确的状态码。

  • 前端与浏览器调试

    在 Network 面板中理解重定向、认证挑战、缓存再验证、WebSocket 升级、资源加载失败和各种 4xx/5xx 响应。

  • SEO 抓取与收录诊断

    检查 301、302、307、308、404、410、429、500、503、软 404、重定向链、临时不可用页面和搜索引擎可见的服务器错误。

  • CDN、网关与负载均衡故障

    区分源站错误、Cloudflare、Nginx、AWS ALB、代理超时、TLS、DNS 和上游不可达问题,避免一开始就误改业务代码。

HTTP 状态码使用建议

HTTP 状态码应该清楚表达协议层结果。响应体可以继续提供业务错误码、字段级提示、traceId、重试建议和帮助链接。

  • 不要因为服务器返回了 JSON,就用 200 包装业务失败。
  • 创建新资源用 201,接受异步任务用 202,操作成功但没有响应体用 204。
  • 请求无法解析用 400,缺少或无效认证用 401,已认证但无权限用 403,资源不存在用 404,资源状态冲突用 409,语义校验失败可用 422。
  • 限流使用 429,并在可以重试时给出等待或重试提示。
  • 非标准厂商状态码不要轻易暴露成公共 API 契约,除非调用方确实需要了解基础设施细节。
  • 面向公开网站时,错误页必须返回正确状态码,避免搜索引擎把软 404 或临时故障页当作正常内容收录。

限制与判断边界

HTTP 状态码是标准化的协议信号,但具体原因还要结合路由、请求方法、请求头、响应体、缓存层、代理链路和服务端日志判断。

  • 单个状态码通常不能证明是谁生成了响应,需要对比应用日志、CDN、网关、代理、负载均衡和源站日志。
  • 一些厂商或实现约定状态码对运维排障很有帮助,但不是可移植的 HTTP 标准语义。
  • 浏览器、API 客户端、搜索引擎爬虫和 SDK 对重定向、认证挑战、缓存和临时响应的处理可能不同。
  • 对外提供 API 时,建议同时文档化 HTTP 状态码和结构化响应体,让调用方有稳定的判断依据。

HTTP 状态码常见问题

围绕使用方式、数据处理、结果判断和常见边界,整理使用前最容易遇到的问题。

01

401 和 403 有什么区别?

401 表示请求缺少有效认证,或者需要认证挑战。403 表示服务器理解了请求,但拒绝执行,通常是调用方没有访问该资源或执行该操作的权限。

02

参数校验失败应该返回 400 还是 422?

请求格式错误、JSON 无法解析、参数类型明显错误时通常用 400。语法正确但字段值不符合业务语义时可以用 422。关键是团队要保持一致,并在接口文档中说明。

03

网站页面应该用 404 还是 410?

资源不存在或不想暴露是否存在时用 404。资源明确永久删除时可以用 410,这对客户端和搜索引擎都更明确。

04

为什么会看到 Cloudflare、Nginx 或 AWS 专用状态码?

这些响应可能由基础设施在请求到达应用前生成,也可能是源站响应异常后由中间层生成。排查时要先看代理、CDN、网关、DNS、TLS、防火墙和负载均衡日志。

05

所有 5xx 都是服务端代码 bug 吗?

不一定。5xx 表示交换过程中的服务端侧失败,但原因可能是上游依赖、维护模式、过载、网关超时、DNS、TLS 或反向代理配置。

继续浏览更多参考工具

如果 HTTP 排查进一步涉及端口、MIME 类型、请求头、URL 行为或其他实现细节,可以继续查看参考分类中的相关工具。