做过几年后端我越来越觉得 HTTP 响应码这套东西属于典型的“看着简单、落地全坑”。你跟前端联调时随手返回一个 200可能让对方多写三行兼容判断你漏掉一个 304可能让 CDN 费用悄悄翻倍你分不清 401 和 403安全评审时就会被追问到说不出话。这篇就借“Http响应码分类汇总”这个题目把五类状态码的语义边界、工程实践和踩坑记录一次讲透希望能给正在写接口、调接口、排查线上问题的同学一份能直接抄作业的参考。1. 先建立整体框架状态码是两端沟通的暗号1.1 五类状态码的划分逻辑HTTP 响应码是服务器对客户端请求给出的结构化回答三位数字按首位分成五大类这个设计比你想的要严谨得多首位类别含义典型状态码1xx信息性请求已接收处理仍在进行100 Continue、101 Switching Protocols、103 Early Hints2xx成功请求已理解并处理成功200 OK、201 Created、204 No Content、206 Partial Content3xx重定向需要客户端做进一步操作301 Moved Permanently、302 Found、304 Not Modified、307/3084xx客户端错误请求本身有问题服务器拒绝400、401、403、404、409、422、4295xx服务端错误服务器处理时出错500 Internal Server Error、502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout这套分类的核心逻辑是“责任划分”1xx 和 2xx 表示服务器接收并处理了请求3xx 表示资源位置或状态发生了变化4xx 表明问题出在请求方5xx 表明问题出在服务端。搞清楚这个责任边界排查问题时思路就清晰很多——看到 4xx 先查自己的参数和权限看到 5xx 再去翻服务端日志而不是在两端之间来回踢皮球。1.2 状态码在整条链路中的实际流转单独看一个状态码意义有限真正有用的是看清它在整条链路里的流转方式。一次典型的现代请求会经过客户端、DNS、CDN、网关、应用服务、数据库等多个节点每一跳都可能改写状态码CDN 回源失败时可能返回 502源站根本没收到请求网关超时会返回 504应用服务其实还在慢慢处理浏览器遇到 301/302 会主动跟进跳转最终你看到的可能是 200。排查线上问题时我习惯先确认“这个状态码是谁返回的”。最简单的办法是用curl -v或浏览器开发者工具看响应头里的 Server 字段再配合网关和 CDN 的访问日志定位。不同节点返回的相同状态码排查方向完全不一样。2. 2xx 成功族不只是 200 这一种结局2.1 不同成功码的语义边界很多团队整个接口层只有一个 200所有场景都往里塞。这不是不行但会丢失语义信息。2xx 家族里有几个成员值得单独拎出来说201 Created用于创建资源成功的场景比 200 更精确。按规范建议响应里应包含 Location 头指向新资源实践中不少团队忽略了这一点。204 No Content表示请求成功但响应体为空常用于 DELETE 操作。它的特点是浏览器不会拿响应体做解析前端拿到 204 后不需要处理 body。206 Partial Content用于 Range 请求的部分内容返回是断点续传、分片下载的基础。如果服务器支持 Range 而不正确处理 206大文件下载体验会很差。2.2 最容易被误用的 200 返回我在联调中见过最多的反面案例是“永远返回 200业务错误码放在 body 里”的写法。比如用户不存在时返回curl -i https://api.example.com/v1/users/10086实际响应是HTTP/1.1 200 OK Content-Type: application/json {code: 404, message: user not found}这种做法有两个实打实的坏处。第一所有网络层和中间件的监控、重试、缓存策略都基于 HTTP 状态码工作200 意味着“一切正常”错误信息全藏在 body 里日志监控、告警规则全部失效。第二前端处理逻辑变得别扭每个请求都要先判断业务 code 再做分支跟处理真实 HTTP 错误的逻辑完全割裂。我在多个项目里推动过状态码规范化核心原则就一句话传输层错误用 HTTP 状态码表达业务层错误在 body 里补充细节两者不要混在一起。2.3 204 与 206 的实战细节先说 204。删除接口用 204 是很标准的做法但要注意204 响应默认不允许包含 body如果你既想返回 204又在 body 里塞了 JSON部分代理和客户端会吞掉或报错。实测下来配置了严格内容校验的网关甚至会直接把这个响应判为非法。206 则依赖请求头里的 Range 字段服务器需要在响应头里正确返回Content-Range。做过视频点播或大文件下载的同学应该深有体会客户端一上来先发一个Range: bytes0-的探测请求服务器返回206 Partial Content和Accept-Ranges: bytes后续才能真正实现拖拽播放和断点续传。如果服务器不支持 Range 却返回 200 全量内容移动端用户加载视频时就会卡到怀疑人生。3. 3xx 重定向族缓存与跳转的潜规则3.1 301 与 302 的本质区别301 表示永久重定向302 表示临时重定向。这个区别看起来一句话就能说清实际影响相当深远。永久迁移的场景比如换域名、HTTP 转 HTTPS应该用 301。浏览器收到 301 后会缓存跳转结果后续请求直接跳到新地址不再回访旧地址。这里有个容易被忽略的坑301 缓存是有时效的取决于响应头里的Cache-Control或浏览器默认策略一旦配错了缓存时间想修改跳转目标时旧客户端会顽固地守着缓存好几天。302 适合临时场景比如登录跳转、未登录用户被引导到登录页、A/B 实验的流量切换。用 302 的页面每次都需要重新请求原地址服务器可以根据当时的状况动态决定跳转方向。但 302 也有个历史包袱早期浏览器在处理 302 时会把 POST 请求改成 GET导致表单重复提交或丢参数。这个问题在后来的规范中通过 303 See Other、307 Temporary Redirect 做了细分。3.2 307 与 308 的保留方法语义307 和 308 的出现就是为了解决 301/302 在方法转换上的历史遗留问题。307 Temporary Redirect临时重定向且保留原始请求方法和 bodyPOST 还是 POST。308 Permanent Redirect永久重定向同样保留方法。听上去简单但很多框架和网关在实现重定向时默认走的是 301/302这就会引出实际问题一个提交表单的 POST 接口做了 302 跳转用户在部分浏览器和代理环境中会发现请求方法变成 GET参数丢失甚至出现重复提交。我做接口设计时凡是涉及表单提交、文件上传这类需要保留 body 的重定向一律要求后端返回 307 或 308并在文档里明确标注。3.3 304 缓存协商最容易省流量的环节304 Not Modified 是我个人认为最被低估的状态码。它不携带资源内容只告诉客户端“你的缓存还能用”配合ETag或Last-Modified实现条件请求客户端请求时带上If-None-Match: etag或If-Modified-Since: date服务器比对后若资源未变返回 304body 为空客户端继续使用本地缓存网络传输量几乎为零。举个例子静态资源第一次请求时完整下载后续如果配好了 ETag每次协商请求的流量可以忽略不计curl -i -H If-None-Match: abc123 https://cdn.example.com/app.js响应可能只有几行头信息HTTP/1.1 304 Not Modified ETag: abc123这事的经验之谈有两点。一是 304 必须正确配合Cache-Control使用no-cache的意思不是不缓存而是“使用前必须回源校验”很多同学把 no-cache 理解成禁止缓存导致回源压力暴增。二是动态接口也可以做条件请求比如列表数据带上版本号配合 304 能显著降低网关和客户端的重复计算开销。4. 4xx 客户端错误族接口设计的主战场4.1 401 与 403 的边界我把 401 和 403 放在一起讲因为它们被混用的概率实在太高了。401 Unauthorized表示“你是谁”的问题即身份认证失败。按规范响应中应包含WWW-Authenticate头提示客户端如何进行认证。403 Forbidden表示“你是谁已知但你不能做这件事”的问题即权限不足。一个典型的正确用法是访问需要登录的资源但没带 token返回 401带了 token 但该用户没有管理员权限返回 403。实际项目中常见错误包括token 过期后返回 403导致前端无法区分“需要重新登录”和“权限不足”部分后端框架在认证过滤器里直接返回 401连WWW-Authenticate头都不带导致客户端无法触发浏览器的标准认证流程。我排查过的一个真实问题是移动端用户频繁被踢下线。逐个抓包后发现网关对 token 过期的请求统一返回了 403前端逻辑把 403 当成“无权限”处理既不清理本地登录态也不跳转登录页用户就在一个“假登录”状态里反复请求失败接口。改成 401 并让前端统一处理后问题立刻消失。这就是状态码语义错位引发的连锁故障。4.2 422 与 400 的选择400 Bad Request 是最常用的 4xx 状态码但它的语义其实偏向“请求语法错误”服务器无法理解这个请求。现实中接口层最常遇到的是参数校验失败——格式不对、字段缺失、数值超出范围。这类问题严格来说不是“语法错误”而是“请求无法被处理”用 422 Unprocessable Entity 更准确。具体选择逻辑可以参考请求 JSON 解析失败、字段类型完全对不上 → 400请求结构正确但业务校验不通过如用户名已存在、金额超限→ 422请求方法错误比如只允许 POST 的接口收到 GET → 405 Method Not Allowed。实际项目中 400 和 422 用哪个并没有强制标准。我的建议是团队内部保持一致同时在 response body 里统一返回字段级错误明细比如{ message: validation failed, errors: [ {field: age, reason: must be between 18 and 60} ] }前端拿到这样的结构可以直接在表单上高亮报错不用再解析一堆混乱的字符串。4.3 429 限流的正确姿势服务被突发流量打爆的场景相信大家都经历过。429 Too Many Requests 是限流的标准响应但它不只是“告诉你被限了”那么简单有个关键响应头容易被遗漏Retry-After。Retry-After可以告诉客户端“多久之后再来”单位是秒或 HTTP 日期。客户端看到 429 并读到Retry-After后可以实现真正的平滑退避而不是大家一起在下一秒重试导致“限流→重试→再限流”的死循环。做 SDK 的同学尤其要注意遇到 429 时重试是合理的但一定要把Retry-After或指数退避策略加进去否则你的客户端本身就是一个小型流量放大器。4.4 404 的两面性404 指资源不存在本身很直白但在安全场景下它需要额外斟酌。有的接口设计为了避免暴露资源是否存在会在“无权访问”和“不存在”两种情况下统一返回 404这在某些业务场景是合理的。但代价是调试复杂度上升前端拿到 404 时无法区分是路径写错、资源被删还是权限不足。我个人的经验是内部接口以调试体验优先区分 403 和 404对外暴露的接口以安全优先必要时混用。这个取舍没有绝对对错关键是团队要明确场景并在接口文档里写清楚。5. 5xx 服务端错误族从日志到告警的排查路径5.1 500 与 502/504 的不同排查思路5xx 表示服务器端出了状况但不同状态码对应的排查方向差异很大。500 Internal Server Error应用内部异常。常规排查路径是看应用日志里的堆栈重点确认是代码异常、依赖服务报错还是资源耗尽。502 Bad Gateway网关或代理从上游收到了无效响应。常见原因是后端进程崩溃、连接被重置、响应格式非法。503 Service Unavailable服务暂时不可用常见于启动中、维护中或负载过高主动熔断。504 Gateway Timeout网关在等待上游响应时超时。问题多半出在上游处理过慢或网关超时时间配置过短。一个我在生产环境踩过的例子某个内部接口偶发 502应用日志里却看不到任何异常。后来抓了网关日志才发现是后端进程频繁被 OOM Killer 干掉重启后接管的请求返回了异常响应。这时排查的重心就不在业务代码上而在内存监控和容器资源配置上。5.2 网关状态码的定位技巧网关包括 Nginx、负载均衡器、API 网关自己会产生一批状态码它们经常跟业务状态码混在一起。单独看前端收到的 502/504 意义不大我的做法是逐层看链路先看浏览器/客户端收到的状态码再看 CDN 日志确认是否命中了源站接着看网关访问日志找到upstream_status与upstream_response_time最后回到应用日志核对对应时间窗口的异常堆栈。这类问题最有价值的信息往往是“时间戳对应关系”。有一次排查接口偶发 504前后调了大量参数都没解决最后发现是网关到后端的超时时间是 5 秒而后端一个批量导出接口平均耗时 7 秒。单纯调大超时时间就解决了但如果不看日志里 upstream_response_time 的分布这个问题会一直作为“玄学故障”存在。5.3 状态码与监控告警的联动服务端状态码还有一个很重要的工程价值它们是监控告警的基础数据源。稳定运行的系统里5xx 占比应该长期趋近于 0。在监控面板上我一般会同时关注以下指标5xx 绝对数和占比的实时曲线按接口聚合的 4xx 分布用于发现参数错误或恶意扫描429 出现频率用于判断限流阈值是否合理502 与 504 的比例关系用于区分是上游问题还是超时配置问题。告警规则也要跟着状态码分类来设计500 激增多半是发布或依赖故障需要立即处理和回滚502/504 激增要考虑网关和后端的链路健康404 激增则可能是资源被误删或爬虫在扫描路径。告警配得太粗比如所有 5xx 一锅端会让值班同学在无效告警里反复折腾最后失去对告警的敏感度。6. 实际项目中的状态码设计规范速查6.1 后端接口响应的推荐组合光是“理解状态码”还不够落地到项目里需要一套可执行的规范。以下是我在多轮项目迭代中沉淀下来的推荐组合供参考场景状态码说明查询成功200body 返回数据创建成功201建议返回新资源信息及 Location更新成功200返回更新后的完整资源删除成功204无 body 返回异步任务已接收202常用于消息队列投递场景参数格式错误400请求体无法解析业务校验失败422返回字段级错误明细未认证401带上 WWW-Authenticate 头无权限403已认证但越权资源不存在404路径或资源缺失方法不允许405需在 Allow 头列出支持方法资源冲突409如版本冲突、唯一键冲突被限流429带上 Retry-After 头服务端未知异常500返回通用错误信息上游不可用502/504网关层需正确映射这里唯一的强制要求是不要自定义一个不在标准范围内的状态码来传递业务语义。标准状态码是两端和中间链路的共同语言自定义数字只会让网关、监控、客户端 SDK 全部陷入困惑。6.2 状态码语义检查清单接口上线前我习惯带着下面的检查清单做一次状态码语义走查是否所有成功响应都准确区分了 200/201/202/204是否还有“200 body code 判错”的反模式401 和 403 的边界是否清晰token 失效是否明确返回 401重定向场景是否合理选择了 301/302/307/308静态资源的缓存协商是否配置了 ETag 和 304限流接口是否返回了 429 和 Retry-After网关层是否对上游超时、断连做了正确的 504/502 映射这份清单看着琐碎但每一条都对应着我在生产环境里处理过的真实故障。状态码规范本质上是接口契约的一部分契约越清晰前后端协作和问题排查的效率就越高。7. 常见问题与排查技巧实录7.1 浏览器显示状态码为 0 是怎么回事做前端联调时经常会遇到“请求失败状态码是 0”的情况。这个 0 并不是 HTTP 协议里的标准状态码而是浏览器层面的异常表达。常见原因包括跨域请求被 CORS 策略拦截请求根本没发出去请求被浏览器主动取消如页面跳转、请求超时被 AbortController 终止请求发到了不可达地址如断网、DNS 解析失败、证书错误被拦截广告拦截或安全软件阻止了请求。排查时建议先看浏览器开发者工具控制台的报错信息再确认跨域配置和网络可达性。状态码为 0 的问题经常不是因为后端而是浏览器层别在服务器日志里白找半天。7.2 状态码与缓存头联动的坑状态码和缓存头的组合是个容易被忽略但影响极大的细节。比较常见的两个坑第一个是 301 永久重定向默认会被浏览器缓存如果线上配错了跳转目标想改回旧地址时那些已经缓存了 301 的浏览器会一直访问旧目标只能通过给旧地址返回 200 或更换 URL 路径来规避。第二个是把 404 响应配上可缓存头导致错误页面被缓存用户看到的状态码和内容永久停留在错误版本上。我的经验是动态页和错误响应统一加Cache-Control: no-store重定向响应单独评估是否允许缓存。7.3 排查状态码问题的抓包姿势线上排查状态码问题光靠代码和日志往往不够我个人的标准流程是先用curl -v复现请求看到完整的状态码和响应头再抓一次带--resolve或修改 Host 的请求确认直达源站的结果是否一致对比浏览器开发者工具里的性能面板确认是慢、是缓存、还是被拦截最后打开网关与 CDN 的访问日志对准时间戳和upstream_status。这套流程能覆盖九成以上的状态码异常问题。记住一个原则状态码问题很少是“玄学”大多数时候是链路里的某个节点把状态码改写或吞掉了顺着链路逐段确认总能找到真相。7.4 容易被忽略的 1xx 状态码1xx 状态码在日常开发中很少被直接看到因为浏览器和大多数 HTTP 客户端都会自动处理它们。但它们并不是毫无用处。100 Continue客户端发送大数据体前可以先发一个带Expect: 100-continue的请求头服务器返回 100 后再发送正式 body避免大文件上传被无谓拒绝。103 Early Hints服务器在最终响应前提前告知浏览器需要加载的资源可以显著优化首屏速度。实际项目中直接在应用层处理 1xx 的机会不多但理解它们的存在能帮你读懂抓包文件里的奇怪包也能在客户端 SDK 做底层网络库时正确处理这些中间状态。最后分享一点我个人维护这套规范的真实体会状态码分类不是一个“背下来就行”的知识点它在项目里的价值取决于团队是否达成了统一的接口契约。我见过太多项目因为前后端对状态码理解不一致反复爆发“明明是成功的请求前端却提示失败”之类的低质量 Bug。与其每次临时开会扯皮不如把状态码使用规范固化到接口文档、代码模板和自动化测试里。花半天时间把这套语义理清楚后面省下的联调和排障时间是以周计的。 
长河君 · 2026/10/19 4:42:33 · 阅读 1.2k HTTP响应码分类与工程实践：从200到504的状态码语义与避坑指南
做过几年后端我越来越觉得 HTTP 响应码这套东西属于典型的“看着简单、落地全坑”。你跟前端联调时随手返回一个 200可能让对方多写三行兼容判断你漏掉一个 304可能让 CDN 费用悄悄翻倍你分不清 401 和 403安全评审时就会被追问到说不出话。这篇就借“Http响应码分类汇总”这个题目把五类状态码的语义边界、工程实践和踩坑记录一次讲透希望能给正在写接口、调接口、排查线上问题的同学一份能直接抄作业的参考。1. 先建立整体框架状态码是两端沟通的暗号1.1 五类状态码的划分逻辑HTTP 响应码是服务器对客户端请求给出的结构化回答三位数字按首位分成五大类这个设计比你想的要严谨得多首位类别含义典型状态码1xx信息性请求已接收处理仍在进行100 Continue、101 Switching Protocols、103 Early Hints2xx成功请求已理解并处理成功200 OK、201 Created、204 No Content、206 Partial Content3xx重定向需要客户端做进一步操作301 Moved Permanently、302 Found、304 Not Modified、307/3084xx客户端错误请求本身有问题服务器拒绝400、401、403、404、409、422、4295xx服务端错误服务器处理时出错500 Internal Server Error、502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout这套分类的核心逻辑是“责任划分”1xx 和 2xx 表示服务器接收并处理了请求3xx 表示资源位置或状态发生了变化4xx 表明问题出在请求方5xx 表明问题出在服务端。搞清楚这个责任边界排查问题时思路就清晰很多——看到 4xx 先查自己的参数和权限看到 5xx 再去翻服务端日志而不是在两端之间来回踢皮球。1.2 状态码在整条链路中的实际流转单独看一个状态码意义有限真正有用的是看清它在整条链路里的流转方式。一次典型的现代请求会经过客户端、DNS、CDN、网关、应用服务、数据库等多个节点每一跳都可能改写状态码CDN 回源失败时可能返回 502源站根本没收到请求网关超时会返回 504应用服务其实还在慢慢处理浏览器遇到 301/302 会主动跟进跳转最终你看到的可能是 200。排查线上问题时我习惯先确认“这个状态码是谁返回的”。最简单的办法是用curl -v或浏览器开发者工具看响应头里的 Server 字段再配合网关和 CDN 的访问日志定位。不同节点返回的相同状态码排查方向完全不一样。2. 2xx 成功族不只是 200 这一种结局2.1 不同成功码的语义边界很多团队整个接口层只有一个 200所有场景都往里塞。这不是不行但会丢失语义信息。2xx 家族里有几个成员值得单独拎出来说201 Created用于创建资源成功的场景比 200 更精确。按规范建议响应里应包含 Location 头指向新资源实践中不少团队忽略了这一点。204 No Content表示请求成功但响应体为空常用于 DELETE 操作。它的特点是浏览器不会拿响应体做解析前端拿到 204 后不需要处理 body。206 Partial Content用于 Range 请求的部分内容返回是断点续传、分片下载的基础。如果服务器支持 Range 而不正确处理 206大文件下载体验会很差。2.2 最容易被误用的 200 返回我在联调中见过最多的反面案例是“永远返回 200业务错误码放在 body 里”的写法。比如用户不存在时返回curl -i https://api.example.com/v1/users/10086实际响应是HTTP/1.1 200 OK Content-Type: application/json {code: 404, message: user not found}这种做法有两个实打实的坏处。第一所有网络层和中间件的监控、重试、缓存策略都基于 HTTP 状态码工作200 意味着“一切正常”错误信息全藏在 body 里日志监控、告警规则全部失效。第二前端处理逻辑变得别扭每个请求都要先判断业务 code 再做分支跟处理真实 HTTP 错误的逻辑完全割裂。我在多个项目里推动过状态码规范化核心原则就一句话传输层错误用 HTTP 状态码表达业务层错误在 body 里补充细节两者不要混在一起。2.3 204 与 206 的实战细节先说 204。删除接口用 204 是很标准的做法但要注意204 响应默认不允许包含 body如果你既想返回 204又在 body 里塞了 JSON部分代理和客户端会吞掉或报错。实测下来配置了严格内容校验的网关甚至会直接把这个响应判为非法。206 则依赖请求头里的 Range 字段服务器需要在响应头里正确返回Content-Range。做过视频点播或大文件下载的同学应该深有体会客户端一上来先发一个Range: bytes0-的探测请求服务器返回206 Partial Content和Accept-Ranges: bytes后续才能真正实现拖拽播放和断点续传。如果服务器不支持 Range 却返回 200 全量内容移动端用户加载视频时就会卡到怀疑人生。3. 3xx 重定向族缓存与跳转的潜规则3.1 301 与 302 的本质区别301 表示永久重定向302 表示临时重定向。这个区别看起来一句话就能说清实际影响相当深远。永久迁移的场景比如换域名、HTTP 转 HTTPS应该用 301。浏览器收到 301 后会缓存跳转结果后续请求直接跳到新地址不再回访旧地址。这里有个容易被忽略的坑301 缓存是有时效的取决于响应头里的Cache-Control或浏览器默认策略一旦配错了缓存时间想修改跳转目标时旧客户端会顽固地守着缓存好几天。302 适合临时场景比如登录跳转、未登录用户被引导到登录页、A/B 实验的流量切换。用 302 的页面每次都需要重新请求原地址服务器可以根据当时的状况动态决定跳转方向。但 302 也有个历史包袱早期浏览器在处理 302 时会把 POST 请求改成 GET导致表单重复提交或丢参数。这个问题在后来的规范中通过 303 See Other、307 Temporary Redirect 做了细分。3.2 307 与 308 的保留方法语义307 和 308 的出现就是为了解决 301/302 在方法转换上的历史遗留问题。307 Temporary Redirect临时重定向且保留原始请求方法和 bodyPOST 还是 POST。308 Permanent Redirect永久重定向同样保留方法。听上去简单但很多框架和网关在实现重定向时默认走的是 301/302这就会引出实际问题一个提交表单的 POST 接口做了 302 跳转用户在部分浏览器和代理环境中会发现请求方法变成 GET参数丢失甚至出现重复提交。我做接口设计时凡是涉及表单提交、文件上传这类需要保留 body 的重定向一律要求后端返回 307 或 308并在文档里明确标注。3.3 304 缓存协商最容易省流量的环节304 Not Modified 是我个人认为最被低估的状态码。它不携带资源内容只告诉客户端“你的缓存还能用”配合ETag或Last-Modified实现条件请求客户端请求时带上If-None-Match: etag或If-Modified-Since: date服务器比对后若资源未变返回 304body 为空客户端继续使用本地缓存网络传输量几乎为零。举个例子静态资源第一次请求时完整下载后续如果配好了 ETag每次协商请求的流量可以忽略不计curl -i -H If-None-Match: abc123 https://cdn.example.com/app.js响应可能只有几行头信息HTTP/1.1 304 Not Modified ETag: abc123这事的经验之谈有两点。一是 304 必须正确配合Cache-Control使用no-cache的意思不是不缓存而是“使用前必须回源校验”很多同学把 no-cache 理解成禁止缓存导致回源压力暴增。二是动态接口也可以做条件请求比如列表数据带上版本号配合 304 能显著降低网关和客户端的重复计算开销。4. 4xx 客户端错误族接口设计的主战场4.1 401 与 403 的边界我把 401 和 403 放在一起讲因为它们被混用的概率实在太高了。401 Unauthorized表示“你是谁”的问题即身份认证失败。按规范响应中应包含WWW-Authenticate头提示客户端如何进行认证。403 Forbidden表示“你是谁已知但你不能做这件事”的问题即权限不足。一个典型的正确用法是访问需要登录的资源但没带 token返回 401带了 token 但该用户没有管理员权限返回 403。实际项目中常见错误包括token 过期后返回 403导致前端无法区分“需要重新登录”和“权限不足”部分后端框架在认证过滤器里直接返回 401连WWW-Authenticate头都不带导致客户端无法触发浏览器的标准认证流程。我排查过的一个真实问题是移动端用户频繁被踢下线。逐个抓包后发现网关对 token 过期的请求统一返回了 403前端逻辑把 403 当成“无权限”处理既不清理本地登录态也不跳转登录页用户就在一个“假登录”状态里反复请求失败接口。改成 401 并让前端统一处理后问题立刻消失。这就是状态码语义错位引发的连锁故障。4.2 422 与 400 的选择400 Bad Request 是最常用的 4xx 状态码但它的语义其实偏向“请求语法错误”服务器无法理解这个请求。现实中接口层最常遇到的是参数校验失败——格式不对、字段缺失、数值超出范围。这类问题严格来说不是“语法错误”而是“请求无法被处理”用 422 Unprocessable Entity 更准确。具体选择逻辑可以参考请求 JSON 解析失败、字段类型完全对不上 → 400请求结构正确但业务校验不通过如用户名已存在、金额超限→ 422请求方法错误比如只允许 POST 的接口收到 GET → 405 Method Not Allowed。实际项目中 400 和 422 用哪个并没有强制标准。我的建议是团队内部保持一致同时在 response body 里统一返回字段级错误明细比如{ message: validation failed, errors: [ {field: age, reason: must be between 18 and 60} ] }前端拿到这样的结构可以直接在表单上高亮报错不用再解析一堆混乱的字符串。4.3 429 限流的正确姿势服务被突发流量打爆的场景相信大家都经历过。429 Too Many Requests 是限流的标准响应但它不只是“告诉你被限了”那么简单有个关键响应头容易被遗漏Retry-After。Retry-After可以告诉客户端“多久之后再来”单位是秒或 HTTP 日期。客户端看到 429 并读到Retry-After后可以实现真正的平滑退避而不是大家一起在下一秒重试导致“限流→重试→再限流”的死循环。做 SDK 的同学尤其要注意遇到 429 时重试是合理的但一定要把Retry-After或指数退避策略加进去否则你的客户端本身就是一个小型流量放大器。4.4 404 的两面性404 指资源不存在本身很直白但在安全场景下它需要额外斟酌。有的接口设计为了避免暴露资源是否存在会在“无权访问”和“不存在”两种情况下统一返回 404这在某些业务场景是合理的。但代价是调试复杂度上升前端拿到 404 时无法区分是路径写错、资源被删还是权限不足。我个人的经验是内部接口以调试体验优先区分 403 和 404对外暴露的接口以安全优先必要时混用。这个取舍没有绝对对错关键是团队要明确场景并在接口文档里写清楚。5. 5xx 服务端错误族从日志到告警的排查路径5.1 500 与 502/504 的不同排查思路5xx 表示服务器端出了状况但不同状态码对应的排查方向差异很大。500 Internal Server Error应用内部异常。常规排查路径是看应用日志里的堆栈重点确认是代码异常、依赖服务报错还是资源耗尽。502 Bad Gateway网关或代理从上游收到了无效响应。常见原因是后端进程崩溃、连接被重置、响应格式非法。503 Service Unavailable服务暂时不可用常见于启动中、维护中或负载过高主动熔断。504 Gateway Timeout网关在等待上游响应时超时。问题多半出在上游处理过慢或网关超时时间配置过短。一个我在生产环境踩过的例子某个内部接口偶发 502应用日志里却看不到任何异常。后来抓了网关日志才发现是后端进程频繁被 OOM Killer 干掉重启后接管的请求返回了异常响应。这时排查的重心就不在业务代码上而在内存监控和容器资源配置上。5.2 网关状态码的定位技巧网关包括 Nginx、负载均衡器、API 网关自己会产生一批状态码它们经常跟业务状态码混在一起。单独看前端收到的 502/504 意义不大我的做法是逐层看链路先看浏览器/客户端收到的状态码再看 CDN 日志确认是否命中了源站接着看网关访问日志找到upstream_status与upstream_response_time最后回到应用日志核对对应时间窗口的异常堆栈。这类问题最有价值的信息往往是“时间戳对应关系”。有一次排查接口偶发 504前后调了大量参数都没解决最后发现是网关到后端的超时时间是 5 秒而后端一个批量导出接口平均耗时 7 秒。单纯调大超时时间就解决了但如果不看日志里 upstream_response_time 的分布这个问题会一直作为“玄学故障”存在。5.3 状态码与监控告警的联动服务端状态码还有一个很重要的工程价值它们是监控告警的基础数据源。稳定运行的系统里5xx 占比应该长期趋近于 0。在监控面板上我一般会同时关注以下指标5xx 绝对数和占比的实时曲线按接口聚合的 4xx 分布用于发现参数错误或恶意扫描429 出现频率用于判断限流阈值是否合理502 与 504 的比例关系用于区分是上游问题还是超时配置问题。告警规则也要跟着状态码分类来设计500 激增多半是发布或依赖故障需要立即处理和回滚502/504 激增要考虑网关和后端的链路健康404 激增则可能是资源被误删或爬虫在扫描路径。告警配得太粗比如所有 5xx 一锅端会让值班同学在无效告警里反复折腾最后失去对告警的敏感度。6. 实际项目中的状态码设计规范速查6.1 后端接口响应的推荐组合光是“理解状态码”还不够落地到项目里需要一套可执行的规范。以下是我在多轮项目迭代中沉淀下来的推荐组合供参考场景状态码说明查询成功200body 返回数据创建成功201建议返回新资源信息及 Location更新成功200返回更新后的完整资源删除成功204无 body 返回异步任务已接收202常用于消息队列投递场景参数格式错误400请求体无法解析业务校验失败422返回字段级错误明细未认证401带上 WWW-Authenticate 头无权限403已认证但越权资源不存在404路径或资源缺失方法不允许405需在 Allow 头列出支持方法资源冲突409如版本冲突、唯一键冲突被限流429带上 Retry-After 头服务端未知异常500返回通用错误信息上游不可用502/504网关层需正确映射这里唯一的强制要求是不要自定义一个不在标准范围内的状态码来传递业务语义。标准状态码是两端和中间链路的共同语言自定义数字只会让网关、监控、客户端 SDK 全部陷入困惑。6.2 状态码语义检查清单接口上线前我习惯带着下面的检查清单做一次状态码语义走查是否所有成功响应都准确区分了 200/201/202/204是否还有“200 body code 判错”的反模式401 和 403 的边界是否清晰token 失效是否明确返回 401重定向场景是否合理选择了 301/302/307/308静态资源的缓存协商是否配置了 ETag 和 304限流接口是否返回了 429 和 Retry-After网关层是否对上游超时、断连做了正确的 504/502 映射这份清单看着琐碎但每一条都对应着我在生产环境里处理过的真实故障。状态码规范本质上是接口契约的一部分契约越清晰前后端协作和问题排查的效率就越高。7. 常见问题与排查技巧实录7.1 浏览器显示状态码为 0 是怎么回事做前端联调时经常会遇到“请求失败状态码是 0”的情况。这个 0 并不是 HTTP 协议里的标准状态码而是浏览器层面的异常表达。常见原因包括跨域请求被 CORS 策略拦截请求根本没发出去请求被浏览器主动取消如页面跳转、请求超时被 AbortController 终止请求发到了不可达地址如断网、DNS 解析失败、证书错误被拦截广告拦截或安全软件阻止了请求。排查时建议先看浏览器开发者工具控制台的报错信息再确认跨域配置和网络可达性。状态码为 0 的问题经常不是因为后端而是浏览器层别在服务器日志里白找半天。7.2 状态码与缓存头联动的坑状态码和缓存头的组合是个容易被忽略但影响极大的细节。比较常见的两个坑第一个是 301 永久重定向默认会被浏览器缓存如果线上配错了跳转目标想改回旧地址时那些已经缓存了 301 的浏览器会一直访问旧目标只能通过给旧地址返回 200 或更换 URL 路径来规避。第二个是把 404 响应配上可缓存头导致错误页面被缓存用户看到的状态码和内容永久停留在错误版本上。我的经验是动态页和错误响应统一加Cache-Control: no-store重定向响应单独评估是否允许缓存。7.3 排查状态码问题的抓包姿势线上排查状态码问题光靠代码和日志往往不够我个人的标准流程是先用curl -v复现请求看到完整的状态码和响应头再抓一次带--resolve或修改 Host 的请求确认直达源站的结果是否一致对比浏览器开发者工具里的性能面板确认是慢、是缓存、还是被拦截最后打开网关与 CDN 的访问日志对准时间戳和upstream_status。这套流程能覆盖九成以上的状态码异常问题。记住一个原则状态码问题很少是“玄学”大多数时候是链路里的某个节点把状态码改写或吞掉了顺着链路逐段确认总能找到真相。7.4 容易被忽略的 1xx 状态码1xx 状态码在日常开发中很少被直接看到因为浏览器和大多数 HTTP 客户端都会自动处理它们。但它们并不是毫无用处。100 Continue客户端发送大数据体前可以先发一个带Expect: 100-continue的请求头服务器返回 100 后再发送正式 body避免大文件上传被无谓拒绝。103 Early Hints服务器在最终响应前提前告知浏览器需要加载的资源可以显著优化首屏速度。实际项目中直接在应用层处理 1xx 的机会不多但理解它们的存在能帮你读懂抓包文件里的奇怪包也能在客户端 SDK 做底层网络库时正确处理这些中间状态。最后分享一点我个人维护这套规范的真实体会状态码分类不是一个“背下来就行”的知识点它在项目里的价值取决于团队是否达成了统一的接口契约。我见过太多项目因为前后端对状态码理解不一致反复爆发“明明是成功的请求前端却提示失败”之类的低质量 Bug。与其每次临时开会扯皮不如把状态码使用规范固化到接口文档、代码模板和自动化测试里。花半天时间把这套语义理清楚后面省下的联调和排障时间是以周计的。