HTTP 状态码参考
按状态码、英文短语、分类、来源、生命周期和排查关键词查询 HTTP 响应状态。这个页面覆盖常见 RFC 标准状态码、WebDAV 扩展码、CDN 与代理常见非标准状态码,适合排查 REST API、浏览器请求、SEO 抓取、重定向、认证失败、限流、网关错误和上游超时问题。
- 支持按状态码、英文短语、分类、相关状态码、厂商来源和排查关键词搜索。
- 可以快速对比 1xx、2xx、3xx、4xx、5xx 的语义边界。
- 说明状态码在接口设计、浏览器调试、CDN 故障和服务端排障中的实际用法。
没有找到匹配的 HTTP 状态码。
1xx 信息性响应
最终响应之前的临时响应,通常由 HTTP 客户端、服务器、代理或浏览器网络层处理。
Continue
服务器已收到请求头,客户端可以继续发送请求体。
详情
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,此时应该直接返回最终状态码。
Switching Protocols
服务器同意切换到客户端请求的协议。
详情
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。
Processing
服务器已收到完整请求,正在处理但尚未产生最终响应。
详情
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 的语义。
Early Hints
服务器提前发送可能用于最终响应的提示头。
详情
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。
Upload Resumption Supported
服务器提示当前上传支持中断后的恢复续传。
详情
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。
2xx 成功响应
请求成功相关响应。选择更准确的成功状态码,可以区分已完成、已创建、已接受、无响应体和部分内容等不同语义。
OK
请求已成功处理,并返回了符合请求方法语义的响应。
详情
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 会影响收录质量。
Created
请求已经成功,并且服务器创建了新的资源。
详情
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。
Accepted
请求已被接受处理,但处理尚未完成。
详情
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。
Non-Authoritative Information
响应成功,但内容来自转换或代理后的非权威信息。
详情
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 更容易理解。
No Content
请求成功,但响应不需要返回消息体。
详情
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 表示异步任务已经开始。
Reset Content
请求成功,客户端应重置当前输入视图或表单。
详情
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,除非你明确设计了重置界面语义。
Partial Content
服务器按 Range 请求返回了资源的一部分。
详情
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,否则客户端下载和视频播放很容易出错。
Multi-Status
响应中包含多个资源或多个操作的独立状态结果。
详情
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 却没有逐项结果。
Already Reported
同一 WebDAV 绑定中的成员已经在前面报告过。
详情
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 当成缓存命中或幂等成功。
IM Used
服务器返回的是对当前实例应用增量编码后的结果。
详情
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。
3xx 重定向响应
重定向和缓存相关响应,会影响浏览器跳转、搜索引擎抓取、规范化 URL、API 客户端和重试行为。
Multiple Choices
目标资源有多个可选表示,客户端或用户需要选择其中一个。
详情
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 页面不要让用户和搜索引擎面对不明确的多选入口。
Moved Permanently
资源已经永久移动到新的 URL。
详情
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 更准确。
Found
资源临时位于另一个 URL,客户端可以临时跳转。
详情
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 跳转链。
See Other
客户端应使用 GET 请求另一个 URL 查看结果。
详情
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。
Not Modified
资源未修改,客户端可以继续使用缓存副本。
详情
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 返回完整响应体。
- 不要让错误的缓存头导致用户长期看到旧内容。
Use Proxy
请求资源必须通过代理访问。
详情
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 当普通重定向。
- 不要通过响应强迫客户端使用不可信代理。
Unused
历史保留状态码,目前不再使用。
详情
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 当作可用的重定向状态码。
Temporary Redirect
资源临时重定向,并且客户端不应改变请求方法。
详情
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 代替登录或权限错误。
Permanent Redirect
资源永久重定向,并且客户端不应改变请求方法。
详情
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 循环或长跳转链。
4xx 客户端错误
客户端请求侧问题,包括语法错误、认证、授权、资源不存在、参数校验、状态冲突、限流或法律限制。
Bad Request
请求语法、格式或基础参数错误,服务器无法理解或处理。
详情
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,要说明哪个字段、格式或请求部分有问题。
Unauthorized
请求缺少有效身份认证,客户端需要先登录或提供凭据。
详情
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。
- 不要在响应里暴露过多认证细节。
Payment Required
保留给支付相关场景,标准语义尚未被广泛定义。
详情
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 有统一内置处理。
Forbidden
服务器理解请求,也知道用户是谁,但拒绝执行。
详情
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。
- 不要在响应中泄露敏感权限策略。
Not Found
服务器找不到目标资源,或不愿透露资源是否存在。
详情
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 吞掉。
Method Not Allowed
目标资源存在,但不支持当前 HTTP 方法。
详情
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。
Not Acceptable
服务器无法提供客户端 Accept 头所要求的表示形式。
详情
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 却不说明服务端支持哪些格式。
Proxy Authentication Required
请求需要先通过代理服务器认证。
详情
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。
Request Timeout
服务器等待客户端发送请求的时间过长。
详情
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 掩盖上传大小限制问题。
Conflict
请求与资源当前状态冲突,服务器不能直接完成。
详情
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 却不说明冲突点和恢复方式。
Gone
资源曾经存在,但现在已经永久不可用。
详情
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。
Length Required
服务器要求请求必须提供 Content-Length。
详情
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。
Precondition Failed
条件请求中的前置条件没有通过。
详情
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 或版本号的一致性。
Content Too Large
请求内容超过服务器允许的大小。
详情
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 或网关限制。
- 不要让前端在没有大小提示的情况下反复上传超大文件。
URI Too Long
请求 URI 过长,服务器无法或不愿处理。
详情
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 传递敏感或大量数据。
Unsupported Media Type
服务器不支持请求体的媒体类型或编码格式。
详情
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 却不说明支持哪些媒体类型。
Range Not Satisfiable
Range 请求的范围无法满足。
详情
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。
Expectation Failed
服务器无法满足 Expect 请求头中的期望。
详情
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。
I'm a teapot
彩蛋状态码,表示服务器是茶壶而不能冲咖啡。
详情
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。
Page Expired
页面或会话已过期,常见于 CSRF Token 失效。
详情
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。
- 不要只提示页面过期而不给用户刷新或重新登录的路径。
Enhance Your Calm
客户端请求过于频繁或行为异常,历史上常被用作非标准限流提示。
详情
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。
Misdirected Request
请求被发送到了不能为目标权威处理该请求的服务器。
详情
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、多域名连接复用和反向代理路由错误。
Unprocessable Content
请求格式正确,但语义或业务规则无法通过。
详情
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 却不给字段级错误详情。
Locked
目标资源被锁定,当前请求不能修改它。
详情
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 却不说明锁定原因或恢复方式。
Failed Dependency
请求因依赖的前置操作失败而无法执行。
详情
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,除非确实在表达批处理依赖失败。
Too Early
服务器不愿处理可能被重放的早期数据请求。
详情
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 重放风险时随意使用。
Upgrade Required
服务器要求客户端切换到其他协议后再请求。
详情
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。
Precondition Required
服务器要求请求必须带条件头以避免并发覆盖。
详情
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 却不告诉客户端需要哪个条件头。
Too Many Requests
客户端发送请求过多,被服务端限流。
详情
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 掩盖权限封禁。
Request Header Fields Too Large
请求头过大或被安全策略拒绝的非标准变体。
详情
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 头膨胀。
Request Header Fields Too Large
请求头字段过大,服务器拒绝处理。
详情
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 过大。
Login Time-out
登录会话超时,客户端需要重新认证。
详情
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。
- 不要只提示超时而不引导用户重新登录。
No Response
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 当作源站业务错误。
- 不要误伤健康检查、搜索引擎爬虫或正常用户。
Retry With
请求需要补充信息后重试。
详情
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。
- 不要让调用方猜测需要补充什么信息。
- 缺少参数、未认证或缺少条件头时,应优先选择标准状态码。
Blocked by Windows Parental Controls
请求被 Windows 家长控制或类似策略阻止。
详情
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。
- 不要把它当成服务端业务错误。
Unavailable For Legal Reasons
资源因法律原因不可用。
详情
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。
Client Closed Connection
客户端在负载均衡器响应前关闭连接。
详情
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 日志。
- 不要忽视客户端超时设置和移动网络中断。
Too Many IP Addresses
请求中的 X-Forwarded-For 等头部包含过多 IP 地址。
详情
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 过长或被污染的问题。
- 不要只排查后端代码,应检查代理链路。
Incompatible Protocols
客户端与目标组之间协议不兼容。
详情
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 和目标组协议版本是否匹配。
Request Header Too Large
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 限制。
SSL Certificate Error
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。
SSL Certificate Required
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。
- 不要只提示证书缺失而不说明客户端需要安装或选择证书。
HTTP Request Sent to HTTPS Port
客户端把普通 HTTP 请求发到了 HTTPS 端口。
详情
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 终止层的协议配置。
Invalid Token
Token 无效或已过期的非标准状态码。
详情
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 无效而不说明是否过期、签名错误或权限不足。
Client Closed Request
客户端在服务器响应前主动关闭连接。
详情
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 当作服务器主动失败。
- 不要只查后端错误日志,应用可能根本没有异常。
- 不要忽视前端取消请求、客户端超时和用户关闭页面。
5xx 服务端错误
服务端或网关侧问题,可能来自应用异常、上游依赖、代理、CDN、DNS、TLS、过载、维护或超时。
Internal Server Error
服务器内部发生未知错误,无法完成请求。
详情
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 兜底所有可预期错误。
Not Implemented
服务器不支持完成请求所需的功能。
详情
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 更准确。
Bad Gateway
网关或代理从上游服务器收到无效响应。
详情
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。
- 不要只看浏览器错误页,应查网关和源站日志。
Service Unavailable
服务暂时不可用,通常是过载或维护中。
详情
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 却没有恢复策略。
Gateway Timeout
网关或代理等待上游响应超时。
详情
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。
- 不要只延长超时时间而不优化慢请求。
HTTP Version Not Supported
服务器不支持请求使用的 HTTP 版本。
详情
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。
Variant Also Negotiates
服务器内容协商配置错误,变体资源自身也参与协商。
详情
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。
Insufficient Storage
服务器没有足够存储空间完成请求。
详情
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。
Loop Detected
服务器在处理请求时检测到无限循环。
详情
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。
Bandwidth Limit Exceeded
站点或账户带宽额度已超限。
详情
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。
- 不要只扩容应用,应检查带宽配额、爬虫和静态资源流量。
Not Extended
请求缺少服务器要求的扩展信息;该状态码已经过时。
详情
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 更清楚。
Network Authentication Required
客户端需要先通过网络认证才能访问。
详情
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。
Web Server Returned an Unknown Error
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 和源站日志。
- 不要忽略源站空响应、异常响应头和连接提前关闭。
Web Server Is Down
Cloudflare 无法连接源站,源站拒绝连接或 Web 服务不可用。
详情
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。
Connection Timed Out
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 是连接阶段超时。
- 不要只查应用日志,连接没建立时应用可能没有记录。
- 不要忽略防火墙丢包、安全组和源站过载。
Origin Is Unreachable
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 指向和公网路由可达性。
A Timeout Occurred
Cloudflare 已连接源站,但源站没有及时返回 HTTP 响应。
详情
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 异步处理。
SSL Handshake Failed
Cloudflare 与源站之间 SSL/TLS 握手失败。
详情
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 版本和加密套件。
Invalid SSL Certificate
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 安全模式。
- 不要使用过期、自签名或域名不匹配的源站证书。
Railgun Error
Cloudflare Railgun 到源站发生连接或协议错误。
详情
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 和源站连接配置。
Origin DNS Error
Cloudflare 无法解析源站主机名或遇到源站 DNS 问题。
详情
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 错误码。
Unauthorized
AWS 负载均衡认证失败或身份验证相关错误。
详情
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 认证配置。
Network Read Timeout Error
代理或客户端读取上游响应超时。
详情
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 更偏连接阶段超时。
- 不要只延长读取超时而不优化上游响应。
Network Connect Timeout Error
代理或客户端连接上游超时。
详情
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 混淆。
- 不要只查应用日志,应先确认连接是否建立。
功能简介
这个页面不是只罗列数字和英文短语,而是面向日常接口调试和线上排障整理。每个状态码都把协议含义、常见来源、排查方向和 API 设计建议放在一起,方便前端、后端、测试、运维、SEO 和接口文档维护人员共同使用。
- 01
标准码与扩展码一起查询
覆盖常见 RFC 标准状态码,也包含 WebDAV、Nginx、Cloudflare、AWS 负载均衡、Microsoft/IIS、代理网关和可恢复上传草案中经常看到的扩展或非标准状态码。
- 02
按排查语境搜索
搜索范围不仅包括状态码和短语,也覆盖分类、摘要、来源、相关状态码、常见场景、排查建议和不建议使用的情况。搜索缓存超时WebSocketCloudflare限流等关键词也能定位到相关条目。
- 03
接口设计建议
每个状态码都标明是否适合公共 REST API 或 JSON API 使用,帮助区分可以写进接口文档的稳定语义,以及更适合作为网关、CDN 或内部日志细节保留的状态。
- 04
兼顾运维和 SEO 影响
重定向、软错误、404/410、429 限流、5xx 故障、CDN 网关错误等都按实际影响说明,方便同时处理用户访问、自动化客户端和搜索引擎抓取问题。
如何使用
你可以在查看浏览器开发者工具、服务器日志、API 响应、CDN 面板、负载均衡日志、搜索引擎抓取报告或监控告警时使用这个页面。
- 01
输入你看到的数字状态码、英文短语、厂商名称或故障现象关键词。
- 02
如果已经知道大类,可以先用 1xx、2xx、3xx、4xx、5xx 过滤结果。
- 03
打开匹配条目后先读摘要,再看常见场景,判断这个状态码最可能由哪一层生成。
- 04
修改接口契约前,对比相关状态码。很多问题来自把 200、400、401、403、404、409、422、429、500、502、503、504 混用。
- 05
根据来源和生命周期判断它是否适合写进公共接口文档,还是只应该作为基础设施或内部日志细节。
功能说明
条目结构适合排障时快速阅读,也可以作为接口文档、错误码说明和内部技术手册的参考。
- 状态码数字、英文短语和所属分类。
- 用于快速识别的摘要,以及更完整的语义说明。
- 它在 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 状态码应该清楚表达协议层结果。响应体可以继续提供业务错误码、字段级提示、traceId、重试建议和帮助链接。
- 不要因为服务器返回了 JSON,就用 200 包装业务失败。
- 创建新资源用 201,接受异步任务用 202,操作成功但没有响应体用 204。
- 请求无法解析用 400,缺少或无效认证用 401,已认证但无权限用 403,资源不存在用 404,资源状态冲突用 409,语义校验失败可用 422。
- 限流使用 429,并在可以重试时给出等待或重试提示。
- 非标准厂商状态码不要轻易暴露成公共 API 契约,除非调用方确实需要了解基础设施细节。
- 面向公开网站时,错误页必须返回正确状态码,避免搜索引擎把软 404 或临时故障页当作正常内容收录。
边界与注意事项
HTTP 状态码是标准化的协议信号,但具体原因还要结合路由、请求方法、请求头、响应体、缓存层、代理链路和服务端日志判断。
- 单个状态码通常不能证明是谁生成了响应,需要对比应用日志、CDN、网关、代理、负载均衡和源站日志。
- 一些厂商或实现约定状态码对运维排障很有帮助,但不是可移植的 HTTP 标准语义。
- 浏览器、API 客户端、搜索引擎爬虫和 SDK 对重定向、认证挑战、缓存和临时响应的处理可能不同。
- 对外提供 API 时,建议同时文档化 HTTP 状态码和结构化响应体,让调用方有稳定的判断依据。
常见问题
围绕使用方式、数据处理、结果判断和常见边界,整理使用前最容易遇到的问题。
401 和 403 有什么区别?
401 表示请求缺少有效认证,或者需要认证挑战。403 表示服务器理解了请求,但拒绝执行,通常是调用方没有访问该资源或执行该操作的权限。
参数校验失败应该返回 400 还是 422?
请求格式错误、JSON 无法解析、参数类型明显错误时通常用 400。语法正确但字段值不符合业务语义时可以用 422。关键是团队要保持一致,并在接口文档中说明。
网站页面应该用 404 还是 410?
资源不存在或不想暴露是否存在时用 404。资源明确永久删除时可以用 410,这对客户端和搜索引擎都更明确。
为什么会看到 Cloudflare、Nginx 或 AWS 专用状态码?
这些响应可能由基础设施在请求到达应用前生成,也可能是源站响应异常后由中间层生成。排查时要先看代理、CDN、网关、DNS、TLS、防火墙和负载均衡日志。
所有 5xx 都是服务端代码 bug 吗?
不一定。5xx 表示交换过程中的服务端侧失败,但原因可能是上游依赖、维护模式、过载、网关超时、DNS、TLS 或反向代理配置。