HTTP 状态码查询：70+ 全收录，含义、原因、场景、排查一站全

请求头收到了，客户端可以继续把请求体发出来。配合 Expect: 100-continue 头用，上传大文件前先问一下服务端要不要。

• 客户端发了 Expect: 100-continue 头，准备扔大 body 之前先探一下。
• curl 的 --expect100-timeout 触发。
• gRPC / HTTP2 客户端在试探服务端能不能接。

• 用 PUT 传 2GB 大文件，反代日志里先看到 100 再看到真正的 201。
• API 调用日志里 100 紧跟着真正的 201 出现。

• 不用处理，100 只是中间响应，真正的状态在后头。
• 客户端发完 100 之后挂住，去查服务端解析 body 的逻辑。
• 反代不认 Expect 头，curl 加 -H "Expect:" 把它清掉。

服务端同意按 Upgrade 头切换协议。最常见就是 WebSocket 握手成功的那一下。

• WebSocket 握手 —— 客户端发了 Upgrade: websocket，服务端同意。
• HTTP/2 明文升级握手。
• 业务自定义协议通过 Upgrade 头协商。

• 聊天页打开 WebSocket，DevTools 里先 101 然后一直 pending。
• 实时大屏订阅服务端推送。

• 101 之后 WS 卡住，先看 nginx proxy_read_timeout，默认 60 秒空闲就被剪。
• 确认 nginx 转发了 Upgrade 和 Connection: upgrade 头，并加 proxy_http_version 1.1。
• 前面挂了 CloudFlare / ALB 的话，它们的 idle timeout 也要一起调。

WebDAV 用的中间响应，表示请求已经收到、但处理还没完，让客户端别超时。

• WebDAV 对大目录做 PROPFIND / COPY / MOVE。
• 长时间批量操作，先回 102 让连接别断。

• WebDAV 拷一个 5 万文件的目录。
• Nextcloud / SabreDAV 服务端报进度。

• 不是错误，等真正的响应。
• 大 WebDAV 操作把客户端 / 反代的读超时调大。

服务端在最终响应出来之前先把 Link: rel=preload 这种预加载提示发给浏览器，让浏览器提前拉 CSS/字体/JS，整体首屏更快。

• 服务端在 HTML 渲染完成前先发了 Link: </app.css>; rel=preload。
• CDN（Fastly、Cloudflare）支持 103 并把预加载提示透传。
• 源站用了 Express res.writeEarlyHints() 或 Node 18+ 的 early hints API。

• SSR 应用在 DB 还在查的时候先让浏览器拉字体和关键 CSS。
• 文档站在 HTML 还没拼好时让浏览器先拉头图。

• 103 本身不会出问题，提示被忽略大概率是前置反代把 1xx 整个吞了。
• Chrome 支持，但老一些的反代会把 1xx 全干掉。
• curl -v --http2 验证，看是不是有两份响应。

最经典的成功。请求处理完，body 里就是要的东西。GET 返回资源，POST 返回处理结果。

• GET /api/users —— 资源在，正常返回。
• POST /login —— 登录成功，body 里是 session token。
• 健康检查通过。

• 页面正常加载，数据出来了，用户没意见。
• 监控每分钟打 /healthz，稳稳 200。

• body 错但状态 200 —— 你的 handler 把失败也当成功返回了，把错误分支走一遍。
• POST 创建资源回的是 200 空 body —— 想想是不是 201 更合适。

请求导致新资源被创建，Location 头应该指向它。POST 建资源成功时的正确答案。

• POST /api/users —— 插了一条新用户，返回创建好的对象。
• PUT /api/files/foo.png —— 文件上传到新路径。
• 幂等 PUT 第一次创建资源。

• 注册表单提交后回 201 加新账号 JSON。
• CI 上传构建产物拿到 201 和产物 URL。

• 记得返回 Location 头 —— 前端和集成工具都靠它拿新资源地址。
• 同一个 POST 重复创建同一个资源，第二次应该回 409，或者把接口做成幂等的。

请求收下了但还没处理完。异步任务用这个，回个 job id 让客户端轮询。

• POST /api/export —— 长任务进队列，回 202 加 job_id。
• Webhook handler 收到事件丢进队列就回。
• AI 出图 —— 模型推理排队中。

• 点"导出 10 万行"→ 202 → 前端每 2 秒轮询 /jobs/:id。
• Stripe webhook 回 202 不阻塞上游。

• 一定要给客户端一个查任务的方式：Location 头或 body 里给 job_id。
• 客户端永远等不到完成，去查 worker —— 202 只承诺"收了"，不承诺"会成"。

请求成功，但返回的内容被中间代理改过（比如内容重写代理），不是源站原样。

• 改写型代理重写响应（老式运营商代理）。
• CDN 边缘节点为优化重写 HTML。

• 运营商代理注入压缩提示。
• 边缘 worker 把 HTML 注释清掉。

• 直接 curl 源站对比，看响应是不是被改了。
• 代理改坏了就关掉变换，或者端到端走 HTTPS。

成功，但没 body 要返回。DELETE 和"只更新不回显"的 PUT 就用这个。

• DELETE /api/users/123 —— 删了，没什么要说的。
• PUT /api/settings —— 保存了，不用回显。
• OPTIONS 预检响应（CORS）。

• 设置页保存回 204，前端只显示"已保存"。
• 浏览器 CORS 预检从 API 拿到 204。

• 204 不能带 body —— 某些 HTTP 客户端和反代会出错。
• fetch 拿到 204 时 await res.json() 会抛，先判断 res.status === 204。

告诉客户端把发起请求的界面（一般是表单）重置回初始状态，方便用户再录一条。

• 批量录入表单服务端说"已提交，清空准备下一条"。
• Kiosk / 录入终端的流程。

• 仓库扫码录入 —— 提交完立即清空。

• 和 204 一样，body 必须为空。
• 客户端收到后调一次 form.reset()。

服务端按 Range 头要求只返回了资源的一部分。断点续传、视频拖进度、PDF 按字节拉都用它。

• 视频播放器拖到没缓冲的位置，发 Range: bytes=1048576-。
• 下载暂停后续传。
• PDF.js 按页按需拉取。

• <video> 拉 MP4 带拖动进度条。
• curl -C - 续传大文件。

• 必须带 Content-Range: bytes start-end/total 和 Accept-Ranges: bytes 头。
• nginx 静态服务对 Range 请求回 200 而不是 206 —— 多半是上游 gzip 把 Range 干掉了（nginx 默认对 gzip 内容会忽略 Range）。

WebDAV 用，body 是一段 XML，里面包多个子资源各自的状态。一次请求改多个资源时用。

• WebDAV PROPFIND 一个集合，子节点权限不一样。
• 批量 COPY 一部分目标失败。

• Nextcloud 列一个目录，里面有些文件被锁了。
• CalDAV 批量更新有部分失败。

• 去解析 XML body —— 每个 <response> 都有自己的 <status>。
• 别看到 207 就当全成功，要看里面每个子资源的状态。

WebDAV —— DAV 绑定的成员已经在前面的多状态响应里枚举过，这次不再重复列出。

• 重叠集合的递归 PROPFIND。

• 大型 WebDAV 列表里有交叉引用。

• 不用处理 —— 客户端已经在响应前面看过这些成员了。

HTTP 增量编码 —— 响应是对当前实例做了一种或多种实例操作（比如 delta）的结果。生产中极少见。

• 增量编码响应（RFC 3229），用来在增量更新时省带宽。

• 2000 年代初期带宽紧张的订阅 feed。

• 现在基本用不到 —— gzip + ETag/If-None-Match 解决同类问题更好。

资源有多个表现形式，服务端没法决定挑哪个，让客户端选。很少用，因为自动内容协商已经能搞定多数场景。

• 资源有多种语言 / 格式，没有明确最优选择。

• 某些学术 / 标准化站点的手动内容协商。

• body 里通常会列可选项，带更明确的 Accept 头重发请求。

资源永久搬到 Location 指向的新 URL。浏览器和搜索引擎会狠狠缓存它，配错就把错的 URL 烤进世界里了。

• 站点从 http://example.com 搬到 https://example.com。
• 旧 URL 结构换了（/blog/123 → /posts/123）。
• 品牌改名换域名。

• HTTPS 迁移用 return 301 https://$host$request_uri;。
• SEO：老文章 URL 永久指到新的规范 URL。

• 陷入 301 死循环：清浏览器缓存 + 检查目标 URL 别又 301 回来。
• 上线先用 302 试，新 URL 稳定一周以上再切 301。
• POST 被 301 在老客户端会变成 GET，表单数据丢了。要保留方法和 body 用 308。

临时跳到 Location 指向的 URL。下次客户端还会用原来的 URL。A/B 路由、临时维护页都用它。

• 登录后跳回 ?next=…。
• 按国家跳到本地镜像。
• 表单 POST 完跳 GET（POST/Redirect/GET 模式）。

• 老框架的 redirect() 默认 302 比较保险。
• A/B 测试把 50% 用户路由到 /new/。

• 302 改方法的行为标准上没定，实际浏览器都把 POST 变 GET。明确要 POST→GET 用 303，要保留方法用 307。
• HTTPS 迁移用 301 / 308，别用 302 —— HSTS 和 SEO 永远不认 302。

跳转并把请求方法改成 GET。表单提交后想 POST 跳 GET 的"POST/Redirect/GET 模式"应该用这个。

• POST /orders → 303 Location: /orders/123 —— 浏览器对新 URL 发 GET。
• API 用 303 指到新创建的资源。

• 服务端渲染下单流程：提交购物车 → 303 → 渲染订单页。
• 避免 POST 后刷新页面重复提交。

• 303 之后浏览器没跳走 —— 状态码发错了，确认是 303 不是 200。
• 某些老 HTTP/1.0 客户端把 303 当 302，给它们同时加 Location 和 Cache-Control: no-cache。

条件 GET —— 客户端缓存还有效，资源没变。不返回 body，客户端继续用缓存。

• 客户端发了 If-None-Match: "etag"，ETag 还是一样。
• 客户端发了 If-Modified-Since: <日期>，资源更老。
• CDN 跟源站做 revalidate。

• 刷新静态资源 —— DevTools 里 304，传输 0 字节。
• CDN 出 stale 之前先校验。

• 304 不能带 body，带了缓存层会坏。
• 304 时也要回同样的 ETag 头。
• 客户端永远拿不到 304 —— 检查服务端是不是真的比对了 If-None-Match。

已弃用。原本告诉客户端必须通过特定代理访问资源。因为安全问题浏览器全都忽略。

• 老服务端用了被弃用的语义。

• 现在基本看不到，现代浏览器直接忽略。

• 新代码不要用 305。让客户端通过 HTTP_PROXY 环境变量显式配代理。

保留状态码。已经不再使用 —— 原方案被废弃。生产环境基本看不到。

• 老服务端误用了被废弃的码。

• 基本看不到。

• 不要实现。选另一个能表达真实意图的 3xx。

像 302，但客户端必须保留请求方法和 body。POST 跳转后还是 POST，body 一起带过去。

• API 临时挪了地方，新 URL 还是接同样 payload 的 POST。
• 维护切流量到另一个 region，请求方法不能变。

• Region 容灾切流，POST 要打到备用 endpoint。
• Webhook 接收方临时换了地址。

• 部分 HTTP 库重定向时会把 body 干掉，抓包确认一下。
• 想要"永久 + 保留方法"用 308，不是 307。

像 301，但必须保留方法和 body。需要"永久 + POST 还是 POST"时用它替代 301。

• API 永久换路径，但 POST 客户端不能悄悄变成 GET。
• 上传 endpoint 永久搬家。

• API v1 → v2 路径迁移，要保留 PUT 语义。
• multipart 上传 endpoint 永久搬家。

• 老版 curl / 老客户端不一定认 308，切之前确认调用方支持。
• 只是 URL 规范化、没 body 的话，301 也够用。

服务端没法解析或拒绝处理请求，因为它本身就是错的。"你发的请求格式不对"的兜底。

• JSON body 语法错（多了逗号、引号用错）。
• payload 里必填字段没传。
• query 参数类型错（limit=abc）。
• 请求头单行超过服务端限制。

• 前端 fetch() 之前忘了 JSON.stringify(body)。
• 同事手撸 curl 少了一个大括号。

• 看 response body —— 多数 API 会返回 JSON error 字段说清楚哪错了。
• 用 curl -v 复现，确认 Content-Type 和你发的一致。
• 只有部分客户端中招，怀疑中间反代改了请求头。

名字虽然叫 Unauthorized，但其实是"没认证"—— 没有有效凭据。服务端会通过 WWW-Authenticate 头告诉你怎么登。

• 没带 Authorization 头。
• Bearer token 过期了。
• API key 无效或被吊销。
• 会话 cookie 过期或被清掉。

• 用户开着标签页 24 小时，回来一通操作全 401。
• CI 调 API，碰上 deploy key 刚轮换。

• 刷新 token 或重新登录，重发请求。
• 看 WWW-Authenticate 头，它告诉你要用什么 scheme（Bearer、Basic、Digest）。
• 只过一段时间才 401，去查 token 过期和 refresh-token 流程。
• 服务端要区分：401 是"没凭据/凭据错"，403 才是"凭据对但没权限"。

原本是预留状态码。现在一些 SaaS API 用它表示账号欠费、超配额或试用到期。

• API 账号撞到每月免费额度上限。
• 订阅过期了。
• 按次付费余额清零。

• Stripe 风格：信用卡没续费前每次都 402。
• AI API：预付额度用完了。

• 看 body 里给的扣费 / 充值入口 URL。
• 续费 / 充值后重试。
• 自家 API 用 402 一定在文档里说清楚，客户端默认不会预期。

服务端能理解请求也知道你是谁 —— 但你没权限做这事。和 401（"先登录"）不一样。

• 登录用户去访问别人的资源。
• IP / 地区被封。
• WAF 规则（Cloudflare、AWS WAF）拦截。
• 磁盘文件权限不对 —— nginx error log 里 permission denied。
• 改状态的请求缺 CSRF token。

• 普通用户点了只有管理员能看的链接。
• Cloudflare 拦截可疑流量，丢一个花花绿绿的 403 页。
• 静态站 nginx 回 403，因为文件 chmod 600 了。

• 搞清楚"你是谁"vs"你访问什么"—— 认证通了但权限不够。
• nginx 看 sudo tail -f /var/log/nginx/error.log，会说 Permission denied 或 directory index forbidden。修 chmod / chown 或补文件。
• WAF 误伤？按 URI 或 IP 加白。
• CSRF 的话，刷一下页面拿新 CSRF token 再发。

最经典的。服务端找不到这个 URL 对应的东西。可能压根没存在过、已经删了、或者客户端拼错了 URL。

• URL 路径写错了。
• 资源已经删了。
• 前端代码里写死了老 API 路径。
• SPA 刷新时打到服务端，服务端不认这个路由（没配 try_files / 兜底）。
• 反代 location 块没匹配上。

• SPA 刷新 /dashboard，没配 rewrite，服务端直接 404，不是应用页。
• API 客户端还在打 /v1/，v2 都上线了。
• 文章 URL 改了，旧链接还在外网漂着。

• curl -v 看客户端真正发出去的字节是什么。
• SPA 给 nginx 加 try_files $uri $uri/ /index.html;，或者用框架路由兜底。
• 资源删了的话，做个友好的 404 页带有用链接，别留默认白屏。
• 老 URL 给一条 301 跳到新 URL 找回 SEO。

URL 存在，但你用的 HTTP 方法不支持。服务端应该回 Allow 头列出允许的方法。

• 只接 GET 的接口被 POST 了。
• 只读资源被 DELETE。
• 重构之后前端用错了方法。
• CORS 预检 OPTIONS 打到只处理 GET 的路由上。

• handler 改名时把 POST 分支删了。
• Postman 用 DELETE 调列表端点。

• 看响应里的 Allow 头，列了支持的方法。
• 加上缺的 method handler，或者把客户端改成支持的方法。
• CORS 的话单独写一个 OPTIONS handler 回 204。

服务端没法按客户端 Accept 头要的任意格式产出响应。

• 客户端发了 Accept: application/xml，但 API 只回 JSON。
• 浏览器 Accept-Language 限制太死，服务端没兜底。

• 老 SOAP 客户端对一个只 REST 的 API 要 XML。
• 微服务严格 content negotiation。

• 把客户端 Accept 头改成支持的类型。
• 或者服务端放宽：协商失败时兜底回 application/json。

客户端发完整请求花了太长时间。和 504 不一样 —— 408 是客户端慢，504 是上游慢。

• 网络卡，上传慢。
• 空闲 keep-alive 连接被服务端关了。
• Slowloris 类攻击触发服务端防护。

• 手机信号差时上传照片。
• 服务端 request body timeout 触发。

• 重试一下，多半是临时问题。
• 上传大 body 时把客户端超时调大。
• 服务端调大 nginx 的 client_body_timeout 和 client_header_timeout。

请求和资源当前状态冲突。经典场景是"创建已存在的资源"或"并发编辑"。

• 想注册一个已被占用的用户名。
• 乐观并发检查没过（If-Match ETag 对不上）。
• git push 被拒 —— non-fast-forward。
• 幂等 POST 发现资源已经存在了。

• 两个人同时改同一个 wiki 页，第二个保存的人 409。
• 注册时撞上已被注册的邮箱回 409。

• 告诉用户冲在哪，给"覆盖 / 合并 / 改名"选项。
• ETag 冲突：重新拉一遍 → 再应用变更 → 再提交。
• 加 idempotency key 让重试安全。

资源永久没了，没有新地址。比 404 更强 —— 告诉搜索引擎和客户端这个 URL 可以彻底忘掉。

• 用户注销了账号。
• API 端点下线（过了迁移宽限期）。
• GDPR 删除请求。

• 老 API 路径在 v2 稳定几个月后回 410。
• 已注销用户的主页。

• 想让爬虫主动把 URL 从索引里清掉时，用 410 而不是 404。
• 把下线时间写到文档，让调用方有时间迁。

服务端要求必须带 Content-Length 头，但客户端没发。

• 手撸 HTTP 请求漏了 Content-Length。
• 中间层把 chunked 编码关了。

• telnet 手敲 HTTP 测试。
• 老反代链路不接 chunked POST。

• 请求里加上 Content-Length: <字节数>。
• 或者直接用正经 HTTP 库，自动算好。

请求头里的一个或多个前置条件（If-Match、If-Unmodified-Since 等）判定为假，服务端拒绝执行。

• If-Match 里的 ETag 和资源对不上 —— 别人改过了。
• If-Unmodified-Since 比资源还旧。

• 并发编辑检测 —— 第二个写入方的 ETag 过期了。
• CalDAV / CardDAV 乐观锁。

• 重新 GET 拉新 ETag，合并变更，再写回。
• 把冲突给用户看（和 409 一样），让用户决定留哪份。

请求 body 超过服务端最大限制。上传接口常见。曾经叫 Payload Too Large。

• 用户传 100MB 文件，接口上限是 10MB。
• nginx client_max_body_size 默认 1MB。
• Cloudflare 免费套餐上传上限 100MB。

• 头像上传静默失败 —— nginx 在应用之前就把 413 抛出去了。
• 内部服务发大 JSON payload。

• nginx 在 http / server / location 块加 client_max_body_size 50m; 然后 reload。
• Express: app.use(express.json({ limit: '10mb' }))。
• CloudFlare：超过 100MB 要付费套餐。
• 前端在上传前就告诉用户大小限制，少一次空跑。

URL 比服务端愿意解析的还长。多半是 query 参数太多，或者有人把数据塞 URL 里了。

• GET 里 ?ids=1,2,3,…,9999 几百上千个 ID。
• 服务端 large_client_header_buffers 设得太小。
• 攻击探测发超长 URL。

• 前端"全选再拉"把 5000 个 ID 塞进 query。
• 埋点像素把一层套一层的参数全塞进去。

• 改成 POST 带 body —— URL 不适合塞任意数据。
• 小心调 nginx large_client_header_buffers 4 16k;。
• 用分页代替一把全拉。

客户端发的 Content-Type 服务端没法处理。

• POST 纯文本到一个只接 application/json 的接口。
• 文件上传 multipart boundary 错了。
• JSON fetch 忘了设 Content-Type。

• fetch(url, { body: JSON.stringify(x) }) 没设 headers —— 服务端拿到 text/plain 就拒。
• 图片 API 不收 WebP。

• 客户端设对 Content-Type 头。
• 或者服务端放宽，多接几种类型。

请求里的 Range 头要的字节服务端给不了 —— 通常是超过了文件大小。

• 客户端要 bytes=10000- 但文件只有 5000 字节。
• 负偏移在不支持的服务端上。

• 视频播放器对截断过的文件算错了偏移。
• 断点续传时源文件已经被替换成更小的了。

• 重新拉一次资源大小，再用合法范围请求。
• 服务端要带 Content-Range: bytes */<总长度>，客户端才能纠正。

服务端不能满足请求里 Expect 头的要求。

• 客户端发了 Expect: 100-continue 但服务端不支持。
• 老反代链路破坏了 Expect 语义。

• curl 上传到只支持基础 HTTP 的服务端，被拒。

• 把 Expect 头去掉 —— curl 用 -H "Expect:" 抑制。

愚人节 RFC 2324 的玩笑状态码 —— 茶壶冲不了咖啡。一些站点用它作为对爬虫"走开"的应答。

• 你打了 HTCPCP 茶壶的 /coffee。
• 反爬规则用 418 替代 403。

• /teapot 这种彩蛋。
• Cloudflare worker 对已知爬虫回 418。

• 换台真咖啡机。
• 正经 API 别用 418，挑 403 / 429 / 503。

请求被发到了一个不能产出响应的服务端 —— 通常是 HTTP/2 连接合并把请求发给了不属于该域名的服务器。

• HTTP/2 跨域名连接复用，证书 SAN 对不上。
• 源站绑了错的 IP。

• 多域名 HTTPS 站点共用一个 IP，浏览器错误合并连接。

• 关掉 HTTP/2 连接合并，或者用不同源站 IP。
• 确保证书 SAN 覆盖所有可能合并的域名。

请求语法没问题但语义不对。body 能解析，但字段缺、形状错、过不了校验。

• email 字段写错了，没过格式校验。
• payload 缺必要的关联。
• 数值字段低于允许的最小值。
• Rails / Laravel / FastAPI 校验失败的默认状态码。

• 注册表单密码太弱，API 拒了。
• API 收到不符合 schema 的 JSON。

• 看 body —— 框架一般返回一个 errors map：{ "email": ["格式错"] }。
• 把错误显示到对应表单字段旁，别用通用 toast 兜底。
• 区分解析错（400）和校验错（422）时，校验错用 422 更合适。

WebDAV —— 资源被锁了，请求需要 lock token。

• 其他客户端持有 WebDAV 锁。
• 协作编辑系统强制独占访问。

• 两个用户改同一个 DAV 文件。

• 等锁释放，或者用对的 lock token 解锁。

WebDAV —— 因为依赖的前一个请求失败了，这次也跟着失败。

• PROPPATCH 依赖的前一步被锁或失败。

• WebDAV 批量操作，第二步依赖第一步。

• 找到根因失败修掉，再重发依赖请求。

服务端拒绝处理，因为请求可能是 replay（TLS 1.3 早期数据）。

• TLS 1.3 0-RTT 早期数据被发到非幂等接口。
• 前置反 replay 保护拦了 POST/PUT/DELETE。

• 开了 0-RTT 的 CDN 把 POST 弹回上游。
• Cloudflare 对写接口回 425。

• 写接口关 0-RTT，或者重试 —— 一般就一次。

客户端必须切换到另一种协议（比如 HTTPS、HTTP/2）才能访问。

• HTTP-only 客户端打 HTTPS-only API。
• 服务端为性能要求 HTTP/2。

• 老 IoT 设备遇到服务端升级，要求 TLS。
• gRPC 服务端要求 HTTP/2。

• 看响应里的 Upgrade 头，它告诉你要用什么。
• 把客户端升级到支持的协议。

服务端要求请求必须带条件头（比如 If-Match）以避免"更新丢失"问题。

• PUT 没带 If-Match，但接口要求乐观并发。
• API 强制安全并发编辑。

• wiki API 要求每次保存都带 If-Match: ETag。
• 配置管理 API。

• 请求里加 If-Match: "<etag>" —— etag 从上次 GET 拿。

客户端撞到限流。服务端应该回 Retry-After 头告诉你多久后再试。

• 撞到按 IP 限流（nginx limit_req_zone）。
• API key 超配额。
• 客户端写错了，疯狂重试。
• GitHub / Twitter / OpenAI API 限流。

• 爬虫狂打 API，60 req/min 后开始 429。
• CI 部署时把 webhook 灌爆。

• 看 Retry-After 头 —— 等够时间再重试。指数退避加 jitter。
• 加缓存少打几次。
• 业务上真有需求就找 API 提供方涨配额。
• 自己做服务端的话：429 + Retry-After 比直接断连接友好得多。

请求头总大小或单条字段超过服务端限制。

• cookie 攒到 8KB 以上。
• Authorization 头里塞了巨大 JWT。
• 多个中间件叠加埋点头。

• A/B 测试半年后 cookie 撞上 nginx 默认 8k 头 buffer。
• JWT 里 claim 太多。

• 精简 cookie 和头 —— 清掉过期 A/B 标志、去掉用不上的埋点。
• nginx 小心调 large_client_header_buffers 4 16k;。
• 压缩 JWT claim，或把状态从 token 里挪出去。

nginx 自定义 —— 服务端直接关连接，什么响应都不发。用来静默丢掉不想理的流量，又不暴露后端在监听。

• nginx 配置里对不想要的 Host 头写 return 444;。
• 兜底块对没匹配 server_name 的请求直接 444。

• 反扫描：非真实域名的 Host 一律 444。
• 按 user-agent 干掉机器人流量。

• 自己客户端被 444，看 Host 头是不是和 nginx 配的 server_name 对上。
• 小心用 —— 444 让正常但配错的客户端调试更难。

因法律原因被屏蔽 —— 法院命令、DMCA、GDPR 删除、政府审查。名字来自布拉德伯里的《华氏 451》。

• DMCA 下架。
• GDPR 被遗忘权请求。
• 基于法律的地域屏蔽。

• 音乐平台版权到期后地区屏蔽。
• 新闻文章被法院下架。

• 回 Link 头指到一个解释法律依据的页面。
• 被屏蔽地区的用户访问不了 —— 这就是目的。

nginx 自定义 —— 服务端响应还没发完，客户端就把连接关了。用户没耐心点别处了的常见情况。

• 用户点了停止 / 跳到别处，页面还没加载完。
• 移动 app 取消了在途请求。
• 上游超时比 nginx 等后端的时间更短。

• 慢报表接口 —— 用户等几秒就放弃。
• 手机从 Wi-Fi 切到 4G，请求被切断。

• 把慢接口提速 —— 499 飙说明用户等不及。
• 告警时区分"用户放弃了"（499）和"我们超时"（504）。
• 移动端：看客户端 SDK 的 abort 模式。

服务端撞到没处理的异常。"出问题了但我们没给它更准的状态码"的兜底。

• 应用代码里没 catch 的异常。
• DB 查询报错，handler 没接住。
• 空指针 / 除零 / 类型错。
• 内存爆 / 文件描述符耗尽。

• 新代码路径只有生产数据能踩到的 bug。
• 流量峰值打爆 DB 连接池。
• 依赖库抛了新类型的异常。

• 先看应用日志 —— 堆栈是真朋友。
• 生产挂上 APM / Sentry 抓堆栈。
• 不要把异常原文回给客户端 —— 信息泄露。
• 运维：先看监控里磁盘 / 内存 / FD 上限，别一上来就追代码 bug。

服务端不支持完成请求所需的功能 —— 通常是 HTTP 方法本身就没实现。

• 客户端用了 TRACE 或 CONNECT，服务端没支持。
• gRPC 方法还没实现。
• 占位路由故意回 501。

• 安全扫描工具发 TRACE 测试。
• API 还在开发中。

• 真意思是"以后再做"的话，写到 roadmap。
• 不支持的方法，同时回 Allow 头。

网关 / 反代从上游拿到了无效响应。nginx 说"我连上了但后端给我空响应或垃圾响应"。99% 是上游的问题。

• 后端处理一半崩了。
• 后端没监听预期端口。
• 后端返回的 HTTP 格式不对。
• 上游超时 / 中途关连接。
• SELinux 拦了 nginx → 后端（RHEL/CentOS）。

• 部署时新容器还没起。
• Node 进程崩了 PM2 还没拉起。
• 后端 pod 被 k8s 驱逐。

• 直接打上游：curl -v http://127.0.0.1:3000，连这步都失败说明后端死了，先重启后端看后端日志。
• sudo tail -f /var/log/nginx/error.log —— 常见 connect() failed (111: Connection refused)、upstream prematurely closed connection、no live upstreams。
• RHEL / CentOS 上：setsebool -P httpd_can_network_connect 1 解 SELinux 的坑。
• 调大 nginx 超时不修 502，调超时修的是 504。

服务端在线但暂时处理不了 —— 通常是过载或在维护。应该带 Retry-After。

• 维护窗口 —— 负载均衡主动回 503。
• worker 池满了，队列也满了。
• 限流到并发上限直接丢请求。
• 数据库主从切换中。

• 部署脚本优雅下线老节点。
• 某条爆款带来的流量尖刺。
• 后台任务 worker 池被打爆。

• 看 Retry-After，按退避重试。
• 运维：看监控里 worker / db / 队列饱和度。
• 横向扩 —— 加 worker / 加 pod。
• 维护：回 503 时带一个友好 HTML 页 + Retry-After 头，别白屏。

网关 / 反代等上游等超时了。504 = 上游慢（或卡）；502 = 上游坏了。

• DB 慢查询把后端阻死了。
• 后端死循环或死锁。
• 外部依赖（S3、第三方 API）超时。
• nginx proxy_read_timeout 比后端正常响应时间还短。

• 报表接口跑 3 分钟聚合，反代超时 60 秒。
• AI 推理 90 秒，反代默认超时直接 504。

• 先 profile 慢路径 —— 修慢查询 / 依赖 / 死循环，别只调超时。
• 响应天然就慢（导出、AI），改成异步队列回 202 + job_id。
• nginx 在慢的那个 location 单独 proxy_read_timeout 300s;，别全局加。
• WebSocket 60 秒被切：WS 那个 location 加 proxy_read_timeout 3600s;。

服务端不支持请求的 HTTP 版本。

• 远古客户端只会 HTTP/0.9。
• 反代配置错了，发了错的版本行。

• 90 年代的嵌入式设备打现代服务器。
• HTTP 客户端库写崩了。

• 把客户端升到 HTTP/1.1 或 2。
• 抓包看 —— 版本行应该是 HTTP/1.1。

内容协商配错了，变体又指回另一个变体。极少见。

• Apache mod_negotiation 配错了。
• Transparent Content Negotiation 形成环路。

• 老 Apache 站点的 TCN 配出环。

• 审协商配置，把循环引用拆掉。

服务端没有完成请求所需的存储。WebDAV 风格，但也在上传场景里见过。

• 上传目标磁盘满了。
• WebDAV 配额超了。
• 备份卷空间不够。

• 图床服务的 S3 / 卷容量满了。
• Nextcloud 用户个人配额满。

• 看服务器磁盘使用率。
• 清孤儿上传文件、涨配额、扩卷。

WebDAV —— 服务端在处理请求时检测到死循环（通常是集合里的循环引用）。

• WebDAV 软链环。
• 集合自引用导致的递归 PROPFIND。

• WebDAV 共享里软链指回根目录。

• 把环找出来删掉。
• 审集合引用关系，去掉自环。

服务端需要更多扩展才能完成请求（HTTP 扩展框架，极少用）。

• 客户端没带 RFC 2774 要求的 HTTP 扩展。

• 科研 / 学术领域的特殊协议。

• 看响应给的要求的扩展，客户端实现一下。

客户端必须先认证才能上网。酒店 / 机场 Wi-Fi 强制门户会回这个。

• 酒店 Wi-Fi 强制门户拦了流量。
• 公共 Wi-Fi 服务条款还没确认。

• 酒店大堂打开笔电，所有 HTTPS 请求 511。
• 浏览器检测到 511 自动弹强制门户。

• 打开浏览器接受强制门户条款，再重试。
• 先发一个 HTTP 请求（比如 curl http://detectportal.firefox.com）让门户暴露出来。

Cloudflare 自定义。源站返回了 Cloudflare 没法解释的东西 —— 空响应、异常头、连接被重置。

• 源站响应过程中崩了。
• 源站发了畸形头（比如 Content-Length 无效）。
• 响应中源站发了 RST。

• 源站反代有 bug，把 Content-Length 改乱了。
• 池子里某台源站偶发失败。

• 绕过 Cloudflare（curl --resolve domain:443:<源站 IP>）直接打源站复现。
• 查源站日志有没有崩或 RST。
• 盯响应头有没有异常。

Cloudflare 自定义。源站拒了 TCP 连接。源站 80/443 端口没接连接。

• 源站挂了 / 进程没起。
• 防火墙挡了 Cloudflare 的 IP。
• 源站换了新 IP，DNS / Cloudflare 还没同步。

• 服务器在重启。
• iptables 配错把 443 挡了。

• 把源站起回来；用 curl --resolve 直接打源站 IP 验证。
• 把 Cloudflare IP 段（https://www.cloudflare.com/ips/）在防火墙放行。

Cloudflare 自定义。到源站的 TCP 握手超时 —— 没及时收到 SYN-ACK。

• 源站过载 —— SYN 队列堆积。
• 防火墙静默丢包（DROP 而非 REJECT）Cloudflare 流量。
• Cloudflare 到源站之间路由有问题。

• 源站被 DDoS，内核 SYN 队列满了。
• iptables 规则错了，把新 Cloudflare 网段的包丢了。

• tcpdump -i eth0 port 443 and host <Cloudflare IP> 看 SYN 有没有到。
• 调大 net.core.somaxconn 和 listen backlog。
• 审防火墙和路由。

Cloudflare 自定义。Cloudflare 根本到不了源站 —— DNS 错了、路由不通、或源站 IP 没响应。

• 源站 DNS 记录指向过期 IP。
• BGP 路由问题。
• 源站主机彻底没了。

• 迁了源站但没更新 Cloudflare 记录。
• 云厂商轮换了 IP。

• Cloudflare 控制台核对源站 DNS。
• 找第三方主机 ping / traceroute 源站 IP。

Cloudflare 自定义。TCP 握手成功，但源站发 HTTP 响应太慢（免费版默认 ~100 秒）。

• 长耗时接口（导出、AI、大报表）。
• 源站卡在慢查询。
• 外部依赖慢。

• Cloudflare 后面生成 50MB PDF。
• AI 出图要 3 分钟。

• 把长任务改异步 —— 回 202 + job_id，轮询查完成。
• 用 Cloudflare Workers / Streams 分块响应。
• 企业版能调大超时，但真正答案是改设计。

Cloudflare 自定义。Cloudflare 到源站的 TLS 握手失败 —— 通常是证书 / 协议 / cipher 不匹配。

• 源站证书过期或自签（而 Cloudflare 模式是 Full strict）。
• 源站只支持 SSLv3 / TLS 1.0，Cloudflare 要 1.2+。
• cipher 套件不匹配。

• 忘了续 Let's Encrypt 证书（90 天过期）。
• 老源站挂在花哨 CDN 后面。

• 在外面测：openssl s_client -connect 源站:443 -servername 域名。
• 续源站证书；修 certbot 定时任务。
• Cloudflare SSL 模式临时调成 Full（不是 Full strict）做诊断，别长期这样。

Cloudflare 自定义。Cloudflare 在 Full (strict) 模式下验不过源站证书 —— 域名不对、CA 不被信任、或过期。

• 源站证书的 CN / SAN 不包含该域名。
• 证书由不被信任的 CA 签发。
• 证书过期。

• 源站发自签证书。
• 通配证书没覆盖新子域。

• 给域名签一张公开可信证书（Let's Encrypt 免费）。
• 不想用公开证书，用 Cloudflare Origin CA 证书装到源站。

Cloudflare 自定义。Cloudflare 和 Railgun listener 之间连接失败。基本是历史 —— Railgun 已弃用。

• 源站的 Railgun listener 挂了。
• Cloudflare 和 Railgun 之间网络问题。

• 老的 Cloudflare + Railgun 配置。

• 迁移走，别再用 Railgun —— Cloudflare 已弃用。改用 Argo Smart Routing。

Cloudflare 自定义。响应 body 里通常会带一个 Cloudflare 1xxx 错误码 —— 多半是源站 DNS 坏了、站点被冻结、或者其他 5xx Cloudflare 条件。

• Cloudflare 站点被冻结（账号或域名问题）。
• 源站 DNS 解析不到。
• Argo Tunnel 挂了。

• 源站 DNS 服务器挂了 —— Cloudflare 解析不出来。
• 账号被停。

• 看 body —— Cloudflare 会打印底层 1xxx 错误和帮助链接。
• 看 Cloudflare 控制台账号状态。
• 在外面验证源站 DNS 能解析。