1. 为什么你需要重新认识HTTP状态码很多人做开发或者运维第一次接触HTTP状态码都是在浏览器里看到那个冷冰冰的“404 Not Found”或者调试接口时冒出来的“500 Internal Server Error”。然后随手一搜找到一张状态码对照表扫一眼关掉继续干活。我以前也是这么干的直到有一次线上事故排查了整整两天最后发现根因是一个被忽略的“302”和“307”的区别从那以后我才真正把状态码当回事。HTTP状态码是服务器和客户端之间沟通的语言。你发一个请求过去服务器回一个三位数字这个数字就是它对这次请求的全部态度。三位数字第一位代表大类后面两位代表具体含义。看起来简单但真正吃透它能帮你省下大量排查时间也能让你的API设计更规范、更健壮。这篇文章适合所有跟Web打交道的人——不管你是刚入门的前端、写后端接口的工程师、做自动化测试的QA还是负责线上运维的SRE。我会从实际使用场景出发把状态码的五大类逐一拆开讲清楚重点放在那些容易混淆的、实际工作中高频出现的、以及面试常问的状态码上。每个状态码我都会说清楚三件事它是什么意思、什么场景下会用到、以及用的时候要注意什么坑。2. HTTP状态码的整体分类与设计逻辑2.1 五大类状态码的核心划分HTTP状态码用三位数字表示第一位数字定义了响应的类别后两位没有分类作用。目前RFC标准定义了五大类类别范围核心含义典型场景1xx100-199信息性状态码协议切换、继续发送请求体2xx200-299成功状态码请求被正常处理并返回结果3xx300-399重定向状态码资源位置发生变化需要进一步操作4xx400-499客户端错误请求本身有问题服务器无法处理5xx500-599服务端错误服务器处理请求时发生内部错误这个分类逻辑其实很直观1开头表示“我收到了还在处理”2开头表示“搞定了”3开头表示“你换个地方再试”4开头表示“你发的东西有问题”5开头表示“我这边出问题了”。记住这个口诀大部分场景下你就能快速判断问题出在哪一侧。2.2 状态码的设计哲学语义化沟通状态码的本质是语义化沟通。服务器不需要返回一大段文字来解释发生了什么一个数字就能让客户端知道该怎么处理。比如浏览器看到301就知道要永久跳转并更新书签看到404就知道资源不存在应该展示错误页看到503就知道服务暂时不可用可以稍后重试。这种设计的好处是机器可读。客户端代码可以根据状态码做自动化处理而不需要解析响应体里的文字。比如你的HTTP客户端库看到5xx会自动重试看到4xx就不会重试因为重试也没用——请求本身有问题重试一百次结果都一样。但这里有个常见的误区很多人把所有错误都返回200然后在响应体里放一个{code: 500, message: error}。这种做法直接破坏了HTTP协议的语义让所有中间件、监控系统、客户端库都失去了判断依据。我见过一个项目所有接口都返回200结果Nginx的访问日志里全是200监控完全看不出错误率最后只能靠人工翻日志找问题。状态码该是什么就是什么这是对协议最基本的尊重。2.3 状态码与RESTful API设计的关系如果你在设计RESTful API状态码的选择直接体现了你的设计水平。举个例子GET /users/123返回200表示找到用户返回404表示用户不存在POST /users返回201表示创建成功返回400表示请求体格式错误返回409表示用户名已存在DELETE /users/123返回204表示删除成功且无返回内容返回404表示用户不存在PUT /users/123返回200表示更新成功并返回更新后的资源返回204表示更新成功但不返回内容这些选择不是随意的每一个都有明确的语义。用对了你的API就是自解释的用错了调用方就得靠猜。我个人的经验是在API设计评审时状态码的使用是否规范基本能看出这个团队对HTTP协议的理解深度。3. 2xx成功状态码不只是2003.1 200 OK最常用但不一定最合适200 OK表示请求成功服务器返回了预期的响应体。这是最常见的状态码但很多人把它当成了万能状态码不管什么操作都返回200。实际上200最适合的场景是GET请求成功返回资源或者PUT/PATCH请求成功返回更新后的资源。什么时候不该用200比如创建资源成功后应该用201删除成功后应该用204。我见过一个API创建用户成功后返回200响应体里放了个{id: 123}调用方还得自己判断这是创建成功还是查询成功。如果返回201调用方一看就知道是创建成功了语义清晰得多。注意200的响应体应该包含完整的资源表示或操作结果不要返回空内容。如果确实没有内容可返回考虑204。3.2 201 Created创建资源的正确姿势201表示服务器成功创建了新资源。关键点在于响应头里应该包含Location字段指向新创建资源的URL。比如HTTP/1.1 201 Created Location: /users/456 Content-Type: application/json { id: 456, name: 张三, created_at: 2025-01-15T10:30:00Z }这样客户端就知道新资源的访问地址了不需要自己拼接URL。很多团队忽略了Location头导致客户端创建完资源后还得再发一次查询请求浪费了一次往返。3.3 204 No Content删除和更新的优雅返回204表示请求成功但响应体为空。最适合的场景是DELETE操作成功或者PUT/PATCH更新成功但不需要返回更新后的资源。用204的好处是节省带宽——既然客户端不需要内容那就别传了。但这里有个坑有些客户端库对204的处理不一致。比如某些老版本的HTTP客户端在收到204时会报错因为它期望有响应体。如果你要兼容这类客户端可以在204和200之间做个权衡。我个人的做法是内部服务之间用204对外开放的API用200加一个简单的{success: true}兼容性更好。3.4 206 Partial Content断点续传和大文件下载的基石206表示服务器返回了部分内容通常用于断点续传或分片下载。客户端通过Range头指定要获取的字节范围服务器返回206和对应的片段。GET /large-file.zip HTTP/1.1 Range: bytes0-1023 HTTP/1.1 206 Partial Content Content-Range: bytes 0-1023/1024000 Content-Length: 1024这个状态码在视频流媒体、大文件下载场景中非常关键。如果你做下载服务不支持206就意味着用户每次断网都得从头下载体验极差。实测下来支持Range请求的下载服务用户重试成本降低90%以上。4. 3xx重定向状态码跳转背后的门道4.1 301与302永久与临时的本质区别301 Moved Permanently表示资源永久移动到了新位置302 Found表示资源临时移动到了新位置。这两个状态码看起来只是“永久”和“临时”的区别但实际影响非常大。301的后果浏览器会缓存这个重定向下次直接访问新地址不再请求旧地址。搜索引擎会把旧地址的权重转移到新地址。所以301适合网站改版、域名更换等场景。302的后果浏览器不会缓存每次都会先请求旧地址再跳转。搜索引擎也不会转移权重。302适合临时维护、A/B测试等场景。我踩过的一个坑某次做活动页面用302做了个临时跳转结果活动结束后忘了改回来用户访问旧地址一直被跳到已经下线的活动页。如果用301至少浏览器缓存了之后不会每次都跳。所以用301还是302想清楚这个跳转是永久的还是临时的别拍脑袋决定。4.2 303 See OtherPOST后的重定向标准303表示“去另一个地址看看”通常用于POST请求后的重定向。比如用户提交表单后服务器返回303浏览器会以GET方式请求Location指定的地址。这样可以避免用户刷新页面时重复提交表单。POST /submit-form HTTP/1.1 HTTP/1.1 303 See Other Location: /success这个模式叫Post/Redirect/GetPRG是Web开发中的经典模式。如果你做传统Web应用表单提交后一定要用303重定向否则用户刷新页面就会重复提交。4.3 304 Not Modified缓存优化的关键304表示资源未修改客户端可以使用本地缓存。这个状态码不包含响应体纯粹是为了节省带宽。它的工作机制是客户端发送请求时带上If-Modified-Since或If-None-Match头服务器判断资源是否变化没变化就返回304。GET /style.css HTTP/1.1 If-None-Match: abc123 HTTP/1.1 304 Not Modified ETag: abc123304用好了能大幅提升页面加载速度。我做过一个测试一个包含大量静态资源的页面启用304缓存后二次加载时间从2.3秒降到了0.4秒。但要注意304的配置需要服务器正确设置ETag或Last-Modified否则缓存永远失效。4.4 307与308保持请求方法的重定向307 Temporary Redirect和308 Permanent Redirect与302、301类似但有一个关键区别它们保证重定向后的请求方法不变。比如你发POST请求收到307客户端会用POST请求新地址而302在某些客户端实现中会把POST变成GET。这个区别在API调用中很重要。如果你的API端点临时迁移用307可以保证POST请求还是POST不会变成GET导致请求体丢失。308同理只是它是永久的。提示做API版本迁移时307和308比302和301更安全因为它们不会改变请求方法。5. 4xx客户端错误问题出在请求本身5.1 400 Bad Request笼统但常用的客户端错误400表示服务器无法理解请求通常是因为请求语法错误、参数缺失或格式不对。这是4xx中最笼统的一个很多开发者把所有客户端错误都返回400。但这样做的问题是调用方不知道具体哪里错了。更好的做法是能用更具体的状态码就用更具体的。比如参数校验失败用422未认证用401无权限用403资源不存在用404。400留给真正的“请求格式错误”比如JSON解析失败、请求体过大等。如果确实要用400响应体里一定要包含具体的错误信息告诉调用方哪里错了。比如{ error: invalid_request, message: 字段 email 格式不正确, field: email }5.2 401与403认证与授权的区别这两个状态码经常被搞混。简单说401是“你是谁”403是“你不配”。401 Unauthorized请求未认证或者认证凭证无效。客户端应该重新认证后重试。响应头里应该包含WWW-Authenticate字段告诉客户端怎么认证。403 Forbidden请求已认证但当前用户没有权限访问该资源。重新认证也没用因为问题不是身份而是权限。我见过一个API用户没登录返回403登录了但没权限也返回403调用方完全分不清是该去登录还是该去申请权限。正确的做法是未登录返回401已登录但无权限返回403。5.3 404 Not Found不只是资源不存在404表示服务器找不到请求的资源。这是最常见的状态码之一但它的使用也有一些讲究。首先404不应该用来掩盖403。有些系统为了安全把无权限访问的资源也返回404避免泄露资源是否存在。这种做法在安全敏感场景下是合理的但要在文档中说明。其次404的响应体应该友好。如果是面向用户的页面应该展示一个有用的404页面引导用户回到首页或搜索。如果是API应该返回结构化的错误信息。最后404和410的区别410 Gone表示资源曾经存在但已永久删除。如果你确定资源不会再回来用410比404更准确。搜索引擎看到410会更快地移除索引。5.4 405 Method Not Allowed方法不对405表示请求方法不被允许。比如对一个只支持GET的端点发POST请求就应该返回405。响应头里必须包含Allow字段列出支持的方法HTTP/1.1 405 Method Not Allowed Allow: GET, HEAD这个状态码在API设计中很重要。很多框架默认对不支持的方法返回404这其实是不对的。404表示资源不存在405表示资源存在但不支持这个方法。区分清楚能让调用方更快定位问题。5.5 429 Too Many Requests限流的标配429表示客户端发送了太多请求被服务器限流了。响应头里通常包含Retry-After字段告诉客户端多久后可以重试HTTP/1.1 429 Too Many Requests Retry-After: 60做API限流时429是标准做法。但要注意限流策略要透明。你可以在响应头里包含X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset等信息让调用方知道自己的配额情况。我见过一些API限流了但不说调用方一脸懵只能靠猜。6. 5xx服务端错误问题出在服务器6.1 500 Internal Server Error万能但危险的错误码500表示服务器内部错误是一个笼统的“出问题了”信号。很多框架在捕获到未处理异常时默认返回500。但500的问题是它不告诉调用方具体发生了什么。在生产环境中500的响应体不应该包含堆栈信息或内部细节因为这些可能被攻击者利用。但你应该在服务端日志里记录详细的错误信息方便排查。同时可以给响应体一个追踪ID方便用户反馈问题时定位{ error: internal_error, message: 服务器内部错误请稍后重试, trace_id: abc-123-def }6.2 502 Bad Gateway网关背后的服务挂了502表示网关或代理服务器从上游服务器收到了无效响应。常见场景是Nginx后面的应用服务挂了或者响应格式不对。排查502时重点看上游服务的日志和健康状态。我遇到过一次502排查了半天发现是上游服务返回了一个超大响应头超过了Nginx的默认限制。所以502不一定是服务挂了也可能是响应不符合网关的预期。6.3 503 Service Unavailable服务暂时不可用503表示服务器暂时无法处理请求通常是因为过载或维护。响应头里可以包含Retry-After字段告诉客户端多久后重试。503和502的区别是502是网关收到无效响应503是服务器主动表示自己不可用。做灰度发布或维护时503是一个优雅的降级方式。你可以返回一个友好的维护页面而不是让用户看到连接超时。6.4 504 Gateway Timeout上游服务超时504表示网关等待上游服务响应超时。和502类似问题出在网关和上游服务之间。排查504时重点看上游服务的处理时间是否过长以及网关的超时配置是否合理。我个人的经验是504往往不是上游服务挂了而是它处理某个请求太慢了。可能是数据库慢查询可能是外部API调用超时也可能是代码里有死循环。用链路追踪工具能快速定位。7. 容易被忽略但很重要的状态码7.1 100 Continue大请求体的优化100 Continue表示服务器已经收到请求头客户端可以继续发送请求体。这个状态码用于优化大请求体的传输客户端先发请求头带上Expect: 100-continue服务器如果觉得没问题就返回100客户端再发请求体。如果服务器觉得有问题比如认证失败可以直接返回401客户端就不用浪费带宽发请求体了。POST /upload HTTP/1.1 Expect: 100-continue Content-Length: 10485760 HTTP/1.1 100 Continue [客户端发送10MB请求体]这个机制在上传大文件时很有用但很多客户端和服务器默认不启用。如果你做文件上传服务可以考虑支持这个特性。7.2 101 Switching Protocols协议升级101表示服务器同意切换协议通常用于WebSocket握手。客户端发送Upgrade头服务器同意后返回101之后双方就用新协议通信。GET /chat HTTP/1.1 Upgrade: websocket Connection: Upgrade HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade这个状态码在实时通信场景中很关键。如果你做WebSocket服务101是握手成功的标志。7.3 408 Request Timeout客户端超时408表示服务器等待客户端发送请求超时。这个状态码在实际中不太常见因为大多数服务器会直接关闭连接而不是返回408。但在某些场景下返回408比直接断开更友好因为客户端能明确知道是超时了。7.4 409 Conflict资源冲突409表示请求与当前资源状态冲突。常见场景是并发更新两个客户端同时修改同一条记录后提交的会收到409。或者创建资源时唯一键冲突也可以返回409。{ error: conflict, message: 用户名已被占用, field: username }409比400更具体调用方一看就知道是冲突问题而不是请求格式问题。7.5 410 Gone永久删除410表示资源曾经存在但已永久删除且不会再回来。和404的区别是404是“现在找不到”410是“以前有以后也不会有”。搜索引擎看到410会更快地移除索引。如果你做内容管理系统删除文章后返回410比404更合适能让搜索引擎更快清理。7.6 422 Unprocessable Entity语义错误422表示请求格式正确但语义上有错误。比如JSON能解析但字段值不合法。这个状态码在API校验中很有用比400更具体。{ error: validation_failed, message: 邮箱格式不正确, field: email }我个人的习惯是请求体解析失败用400字段校验失败用422。这样调用方能区分是“请求发错了”还是“请求内容不对”。8. 状态码在实际项目中的使用建议8.1 API设计中的状态码规范做API设计时状态码的选择应该形成团队规范。我建议至少明确以下场景的状态码场景推荐状态码说明查询成功200返回资源列表或详情创建成功201返回Location头和创建的资源更新成功200或204返回更新后资源用200不返回用204删除成功204无响应体参数校验失败422返回具体字段错误未认证401返回WWW-Authenticate头无权限403明确告知无权限资源不存在404返回结构化错误信息方法不支持405返回Allow头限流429返回Retry-After头服务器错误500返回trace_id不暴露细节服务不可用503返回Retry-After头这个规范定下来后所有接口都按这个来调用方就能形成稳定的预期。8.2 监控与告警中的状态码应用状态码是监控的重要维度。你可以按状态码分类统计请求量2xx比例正常请求占比应该占绝大多数4xx比例客户端错误占比突然升高可能意味着有人在扫描或调用方代码有bug5xx比例服务端错误占比这是最关键的告警指标超过阈值就应该告警我个人的经验是5xx比例超过1%就应该关注超过5%就应该告警。4xx比例突然升高也值得关注可能是调用方出了问题。另外不同状态码的告警级别应该不同。500、502、503、504应该高优先级告警400、404可以低优先级或只记录不告警。8.3 排查问题时如何利用状态码排查线上问题时状态码是第一手线索。我的排查思路通常是先看状态码分布确定问题出在客户端还是服务端如果是5xx看具体是500、502、503还是504定位问题环节如果是4xx看是401、403、404还是429判断是认证、权限、路由还是限流问题结合访问日志和错误日志定位具体请求和堆栈举个例子如果突然出现大量504说明上游服务处理超时应该去查上游服务的慢查询或外部依赖。如果突然出现大量502说明上游服务可能挂了或响应格式不对应该去查上游服务的健康状态。8.4 常见误区与避坑指南误区一所有错误都返回200。这是最严重的误区直接破坏了HTTP协议的语义。监控、告警、客户端库全部失效。误区二401和403混用。未认证用401无权限用403别搞反了。误区三404和410混用。永久删除用410临时找不到用404。误区四500响应体暴露堆栈。安全风险攻击者可以利用堆栈信息找到漏洞。误区五重定向用302但期望浏览器缓存。302不会被缓存需要缓存用301。误区六忽略Retry-After头。429和503应该带Retry-After告诉客户端多久后重试。误区七405返回404。方法不支持应该返回405并带Allow头不是404。提示状态码的选择没有绝对的对错但一旦团队形成规范就应该严格遵守。一致性比“最优选择”更重要。9. 几个真实场景的状态码排查实录9.1 场景一接口偶发502的排查过程某次线上服务偶发502频率不高但持续存在。排查思路查看Nginx错误日志发现upstream sent invalid header错误定位到上游服务返回的响应头中包含非法字符进一步排查发现是某个业务字段被直接放进了响应头字段值包含换行符修复对响应头字段做过滤移除非法字符这个案例说明502不一定是服务挂了也可能是响应不符合网关预期。排查时要看网关的错误日志而不仅仅是上游服务的日志。9.2 场景二304缓存导致的样式不更新某次前端发版后部分用户反馈样式没更新。排查思路确认CDN和浏览器缓存都配置了304检查ETag生成逻辑发现是基于文件修改时间生成的发版时文件内容变了但修改时间没变构建工具的问题修复ETag改用文件内容哈希生成这个案例说明304缓存用好了是优化用不好就是坑。ETag的生成逻辑一定要可靠基于内容哈希比基于时间更安全。9.3 场景三429限流导致的调用方雪崩某次调用方反馈接口大量失败排查发现是429。原因是调用方没有处理429收到429后立即重试导致请求量翻倍触发更严格的限流。修复方案调用方增加指数退避重试逻辑服务端在429响应中明确返回Retry-After双方约定限流配额和重试策略这个案例说明429不是返回了就完事调用方必须正确处理。否则限流反而会加剧问题。10. 状态码速查与个人经验总结10.1 高频状态码速查表状态码含义典型场景注意事项200成功GET查询成功返回完整资源201已创建POST创建成功带Location头204无内容DELETE成功无响应体301永久重定向域名更换浏览器会缓存302临时重定向临时跳转不缓存304未修改缓存有效无响应体307临时重定向API迁移保持请求方法308永久重定向API永久迁移保持请求方法400请求错误格式错误返回具体错误401未认证未登录带WWW-Authenticate403无权限已登录但无权限不重新认证404不存在资源找不到友好错误页405方法不允许方法不对带Allow头409冲突并发更新返回冲突详情410已删除永久删除搜索引擎移除422语义错误字段校验失败返回字段错误429限流请求过多带Retry-After500服务器错误未处理异常不暴露堆栈502网关错误上游无效响应查上游日志503不可用维护或过载带Retry-After504网关超时上游超时查慢查询10.2 我个人的使用心得做了这么多年开发我对状态码最大的体会是它是HTTP协议里最被低估的部分。很多人觉得状态码就是几个数字背下来就行。但实际上状态码用得好不好直接反映了一个团队对HTTP协议的理解深度。我的建议是下次你写接口的时候花五分钟想想该用哪个状态码。创建用201删除用204校验失败用422限流用429。这些细节积累起来你的API就会变得自解释、易调试、好维护。还有一点状态码是给机器看的错误信息是给人看的。两者都要做好。状态码让客户端能自动化处理错误信息让开发者能快速定位问题。缺一不可。最后分享一个我踩过的坑曾经有个接口所有错误都返回200响应体里放{code: 500}。后来接入监控系统时发现所有请求都是200错误率永远是0。排查线上问题时完全看不出异常只能人工翻日志。后来花了整整一周把所有接口的状态码改对监控才真正发挥作用。状态码这件事早改早受益。 
长河君 · 2026/10/19 3:38:03 · 阅读 1.2k HTTP状态码深度解析：从301与302的区别到RESTful API设计实践
1. 为什么你需要重新认识HTTP状态码很多人做开发或者运维第一次接触HTTP状态码都是在浏览器里看到那个冷冰冰的“404 Not Found”或者调试接口时冒出来的“500 Internal Server Error”。然后随手一搜找到一张状态码对照表扫一眼关掉继续干活。我以前也是这么干的直到有一次线上事故排查了整整两天最后发现根因是一个被忽略的“302”和“307”的区别从那以后我才真正把状态码当回事。HTTP状态码是服务器和客户端之间沟通的语言。你发一个请求过去服务器回一个三位数字这个数字就是它对这次请求的全部态度。三位数字第一位代表大类后面两位代表具体含义。看起来简单但真正吃透它能帮你省下大量排查时间也能让你的API设计更规范、更健壮。这篇文章适合所有跟Web打交道的人——不管你是刚入门的前端、写后端接口的工程师、做自动化测试的QA还是负责线上运维的SRE。我会从实际使用场景出发把状态码的五大类逐一拆开讲清楚重点放在那些容易混淆的、实际工作中高频出现的、以及面试常问的状态码上。每个状态码我都会说清楚三件事它是什么意思、什么场景下会用到、以及用的时候要注意什么坑。2. HTTP状态码的整体分类与设计逻辑2.1 五大类状态码的核心划分HTTP状态码用三位数字表示第一位数字定义了响应的类别后两位没有分类作用。目前RFC标准定义了五大类类别范围核心含义典型场景1xx100-199信息性状态码协议切换、继续发送请求体2xx200-299成功状态码请求被正常处理并返回结果3xx300-399重定向状态码资源位置发生变化需要进一步操作4xx400-499客户端错误请求本身有问题服务器无法处理5xx500-599服务端错误服务器处理请求时发生内部错误这个分类逻辑其实很直观1开头表示“我收到了还在处理”2开头表示“搞定了”3开头表示“你换个地方再试”4开头表示“你发的东西有问题”5开头表示“我这边出问题了”。记住这个口诀大部分场景下你就能快速判断问题出在哪一侧。2.2 状态码的设计哲学语义化沟通状态码的本质是语义化沟通。服务器不需要返回一大段文字来解释发生了什么一个数字就能让客户端知道该怎么处理。比如浏览器看到301就知道要永久跳转并更新书签看到404就知道资源不存在应该展示错误页看到503就知道服务暂时不可用可以稍后重试。这种设计的好处是机器可读。客户端代码可以根据状态码做自动化处理而不需要解析响应体里的文字。比如你的HTTP客户端库看到5xx会自动重试看到4xx就不会重试因为重试也没用——请求本身有问题重试一百次结果都一样。但这里有个常见的误区很多人把所有错误都返回200然后在响应体里放一个{code: 500, message: error}。这种做法直接破坏了HTTP协议的语义让所有中间件、监控系统、客户端库都失去了判断依据。我见过一个项目所有接口都返回200结果Nginx的访问日志里全是200监控完全看不出错误率最后只能靠人工翻日志找问题。状态码该是什么就是什么这是对协议最基本的尊重。2.3 状态码与RESTful API设计的关系如果你在设计RESTful API状态码的选择直接体现了你的设计水平。举个例子GET /users/123返回200表示找到用户返回404表示用户不存在POST /users返回201表示创建成功返回400表示请求体格式错误返回409表示用户名已存在DELETE /users/123返回204表示删除成功且无返回内容返回404表示用户不存在PUT /users/123返回200表示更新成功并返回更新后的资源返回204表示更新成功但不返回内容这些选择不是随意的每一个都有明确的语义。用对了你的API就是自解释的用错了调用方就得靠猜。我个人的经验是在API设计评审时状态码的使用是否规范基本能看出这个团队对HTTP协议的理解深度。3. 2xx成功状态码不只是2003.1 200 OK最常用但不一定最合适200 OK表示请求成功服务器返回了预期的响应体。这是最常见的状态码但很多人把它当成了万能状态码不管什么操作都返回200。实际上200最适合的场景是GET请求成功返回资源或者PUT/PATCH请求成功返回更新后的资源。什么时候不该用200比如创建资源成功后应该用201删除成功后应该用204。我见过一个API创建用户成功后返回200响应体里放了个{id: 123}调用方还得自己判断这是创建成功还是查询成功。如果返回201调用方一看就知道是创建成功了语义清晰得多。注意200的响应体应该包含完整的资源表示或操作结果不要返回空内容。如果确实没有内容可返回考虑204。3.2 201 Created创建资源的正确姿势201表示服务器成功创建了新资源。关键点在于响应头里应该包含Location字段指向新创建资源的URL。比如HTTP/1.1 201 Created Location: /users/456 Content-Type: application/json { id: 456, name: 张三, created_at: 2025-01-15T10:30:00Z }这样客户端就知道新资源的访问地址了不需要自己拼接URL。很多团队忽略了Location头导致客户端创建完资源后还得再发一次查询请求浪费了一次往返。3.3 204 No Content删除和更新的优雅返回204表示请求成功但响应体为空。最适合的场景是DELETE操作成功或者PUT/PATCH更新成功但不需要返回更新后的资源。用204的好处是节省带宽——既然客户端不需要内容那就别传了。但这里有个坑有些客户端库对204的处理不一致。比如某些老版本的HTTP客户端在收到204时会报错因为它期望有响应体。如果你要兼容这类客户端可以在204和200之间做个权衡。我个人的做法是内部服务之间用204对外开放的API用200加一个简单的{success: true}兼容性更好。3.4 206 Partial Content断点续传和大文件下载的基石206表示服务器返回了部分内容通常用于断点续传或分片下载。客户端通过Range头指定要获取的字节范围服务器返回206和对应的片段。GET /large-file.zip HTTP/1.1 Range: bytes0-1023 HTTP/1.1 206 Partial Content Content-Range: bytes 0-1023/1024000 Content-Length: 1024这个状态码在视频流媒体、大文件下载场景中非常关键。如果你做下载服务不支持206就意味着用户每次断网都得从头下载体验极差。实测下来支持Range请求的下载服务用户重试成本降低90%以上。4. 3xx重定向状态码跳转背后的门道4.1 301与302永久与临时的本质区别301 Moved Permanently表示资源永久移动到了新位置302 Found表示资源临时移动到了新位置。这两个状态码看起来只是“永久”和“临时”的区别但实际影响非常大。301的后果浏览器会缓存这个重定向下次直接访问新地址不再请求旧地址。搜索引擎会把旧地址的权重转移到新地址。所以301适合网站改版、域名更换等场景。302的后果浏览器不会缓存每次都会先请求旧地址再跳转。搜索引擎也不会转移权重。302适合临时维护、A/B测试等场景。我踩过的一个坑某次做活动页面用302做了个临时跳转结果活动结束后忘了改回来用户访问旧地址一直被跳到已经下线的活动页。如果用301至少浏览器缓存了之后不会每次都跳。所以用301还是302想清楚这个跳转是永久的还是临时的别拍脑袋决定。4.2 303 See OtherPOST后的重定向标准303表示“去另一个地址看看”通常用于POST请求后的重定向。比如用户提交表单后服务器返回303浏览器会以GET方式请求Location指定的地址。这样可以避免用户刷新页面时重复提交表单。POST /submit-form HTTP/1.1 HTTP/1.1 303 See Other Location: /success这个模式叫Post/Redirect/GetPRG是Web开发中的经典模式。如果你做传统Web应用表单提交后一定要用303重定向否则用户刷新页面就会重复提交。4.3 304 Not Modified缓存优化的关键304表示资源未修改客户端可以使用本地缓存。这个状态码不包含响应体纯粹是为了节省带宽。它的工作机制是客户端发送请求时带上If-Modified-Since或If-None-Match头服务器判断资源是否变化没变化就返回304。GET /style.css HTTP/1.1 If-None-Match: abc123 HTTP/1.1 304 Not Modified ETag: abc123304用好了能大幅提升页面加载速度。我做过一个测试一个包含大量静态资源的页面启用304缓存后二次加载时间从2.3秒降到了0.4秒。但要注意304的配置需要服务器正确设置ETag或Last-Modified否则缓存永远失效。4.4 307与308保持请求方法的重定向307 Temporary Redirect和308 Permanent Redirect与302、301类似但有一个关键区别它们保证重定向后的请求方法不变。比如你发POST请求收到307客户端会用POST请求新地址而302在某些客户端实现中会把POST变成GET。这个区别在API调用中很重要。如果你的API端点临时迁移用307可以保证POST请求还是POST不会变成GET导致请求体丢失。308同理只是它是永久的。提示做API版本迁移时307和308比302和301更安全因为它们不会改变请求方法。5. 4xx客户端错误问题出在请求本身5.1 400 Bad Request笼统但常用的客户端错误400表示服务器无法理解请求通常是因为请求语法错误、参数缺失或格式不对。这是4xx中最笼统的一个很多开发者把所有客户端错误都返回400。但这样做的问题是调用方不知道具体哪里错了。更好的做法是能用更具体的状态码就用更具体的。比如参数校验失败用422未认证用401无权限用403资源不存在用404。400留给真正的“请求格式错误”比如JSON解析失败、请求体过大等。如果确实要用400响应体里一定要包含具体的错误信息告诉调用方哪里错了。比如{ error: invalid_request, message: 字段 email 格式不正确, field: email }5.2 401与403认证与授权的区别这两个状态码经常被搞混。简单说401是“你是谁”403是“你不配”。401 Unauthorized请求未认证或者认证凭证无效。客户端应该重新认证后重试。响应头里应该包含WWW-Authenticate字段告诉客户端怎么认证。403 Forbidden请求已认证但当前用户没有权限访问该资源。重新认证也没用因为问题不是身份而是权限。我见过一个API用户没登录返回403登录了但没权限也返回403调用方完全分不清是该去登录还是该去申请权限。正确的做法是未登录返回401已登录但无权限返回403。5.3 404 Not Found不只是资源不存在404表示服务器找不到请求的资源。这是最常见的状态码之一但它的使用也有一些讲究。首先404不应该用来掩盖403。有些系统为了安全把无权限访问的资源也返回404避免泄露资源是否存在。这种做法在安全敏感场景下是合理的但要在文档中说明。其次404的响应体应该友好。如果是面向用户的页面应该展示一个有用的404页面引导用户回到首页或搜索。如果是API应该返回结构化的错误信息。最后404和410的区别410 Gone表示资源曾经存在但已永久删除。如果你确定资源不会再回来用410比404更准确。搜索引擎看到410会更快地移除索引。5.4 405 Method Not Allowed方法不对405表示请求方法不被允许。比如对一个只支持GET的端点发POST请求就应该返回405。响应头里必须包含Allow字段列出支持的方法HTTP/1.1 405 Method Not Allowed Allow: GET, HEAD这个状态码在API设计中很重要。很多框架默认对不支持的方法返回404这其实是不对的。404表示资源不存在405表示资源存在但不支持这个方法。区分清楚能让调用方更快定位问题。5.5 429 Too Many Requests限流的标配429表示客户端发送了太多请求被服务器限流了。响应头里通常包含Retry-After字段告诉客户端多久后可以重试HTTP/1.1 429 Too Many Requests Retry-After: 60做API限流时429是标准做法。但要注意限流策略要透明。你可以在响应头里包含X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset等信息让调用方知道自己的配额情况。我见过一些API限流了但不说调用方一脸懵只能靠猜。6. 5xx服务端错误问题出在服务器6.1 500 Internal Server Error万能但危险的错误码500表示服务器内部错误是一个笼统的“出问题了”信号。很多框架在捕获到未处理异常时默认返回500。但500的问题是它不告诉调用方具体发生了什么。在生产环境中500的响应体不应该包含堆栈信息或内部细节因为这些可能被攻击者利用。但你应该在服务端日志里记录详细的错误信息方便排查。同时可以给响应体一个追踪ID方便用户反馈问题时定位{ error: internal_error, message: 服务器内部错误请稍后重试, trace_id: abc-123-def }6.2 502 Bad Gateway网关背后的服务挂了502表示网关或代理服务器从上游服务器收到了无效响应。常见场景是Nginx后面的应用服务挂了或者响应格式不对。排查502时重点看上游服务的日志和健康状态。我遇到过一次502排查了半天发现是上游服务返回了一个超大响应头超过了Nginx的默认限制。所以502不一定是服务挂了也可能是响应不符合网关的预期。6.3 503 Service Unavailable服务暂时不可用503表示服务器暂时无法处理请求通常是因为过载或维护。响应头里可以包含Retry-After字段告诉客户端多久后重试。503和502的区别是502是网关收到无效响应503是服务器主动表示自己不可用。做灰度发布或维护时503是一个优雅的降级方式。你可以返回一个友好的维护页面而不是让用户看到连接超时。6.4 504 Gateway Timeout上游服务超时504表示网关等待上游服务响应超时。和502类似问题出在网关和上游服务之间。排查504时重点看上游服务的处理时间是否过长以及网关的超时配置是否合理。我个人的经验是504往往不是上游服务挂了而是它处理某个请求太慢了。可能是数据库慢查询可能是外部API调用超时也可能是代码里有死循环。用链路追踪工具能快速定位。7. 容易被忽略但很重要的状态码7.1 100 Continue大请求体的优化100 Continue表示服务器已经收到请求头客户端可以继续发送请求体。这个状态码用于优化大请求体的传输客户端先发请求头带上Expect: 100-continue服务器如果觉得没问题就返回100客户端再发请求体。如果服务器觉得有问题比如认证失败可以直接返回401客户端就不用浪费带宽发请求体了。POST /upload HTTP/1.1 Expect: 100-continue Content-Length: 10485760 HTTP/1.1 100 Continue [客户端发送10MB请求体]这个机制在上传大文件时很有用但很多客户端和服务器默认不启用。如果你做文件上传服务可以考虑支持这个特性。7.2 101 Switching Protocols协议升级101表示服务器同意切换协议通常用于WebSocket握手。客户端发送Upgrade头服务器同意后返回101之后双方就用新协议通信。GET /chat HTTP/1.1 Upgrade: websocket Connection: Upgrade HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade这个状态码在实时通信场景中很关键。如果你做WebSocket服务101是握手成功的标志。7.3 408 Request Timeout客户端超时408表示服务器等待客户端发送请求超时。这个状态码在实际中不太常见因为大多数服务器会直接关闭连接而不是返回408。但在某些场景下返回408比直接断开更友好因为客户端能明确知道是超时了。7.4 409 Conflict资源冲突409表示请求与当前资源状态冲突。常见场景是并发更新两个客户端同时修改同一条记录后提交的会收到409。或者创建资源时唯一键冲突也可以返回409。{ error: conflict, message: 用户名已被占用, field: username }409比400更具体调用方一看就知道是冲突问题而不是请求格式问题。7.5 410 Gone永久删除410表示资源曾经存在但已永久删除且不会再回来。和404的区别是404是“现在找不到”410是“以前有以后也不会有”。搜索引擎看到410会更快地移除索引。如果你做内容管理系统删除文章后返回410比404更合适能让搜索引擎更快清理。7.6 422 Unprocessable Entity语义错误422表示请求格式正确但语义上有错误。比如JSON能解析但字段值不合法。这个状态码在API校验中很有用比400更具体。{ error: validation_failed, message: 邮箱格式不正确, field: email }我个人的习惯是请求体解析失败用400字段校验失败用422。这样调用方能区分是“请求发错了”还是“请求内容不对”。8. 状态码在实际项目中的使用建议8.1 API设计中的状态码规范做API设计时状态码的选择应该形成团队规范。我建议至少明确以下场景的状态码场景推荐状态码说明查询成功200返回资源列表或详情创建成功201返回Location头和创建的资源更新成功200或204返回更新后资源用200不返回用204删除成功204无响应体参数校验失败422返回具体字段错误未认证401返回WWW-Authenticate头无权限403明确告知无权限资源不存在404返回结构化错误信息方法不支持405返回Allow头限流429返回Retry-After头服务器错误500返回trace_id不暴露细节服务不可用503返回Retry-After头这个规范定下来后所有接口都按这个来调用方就能形成稳定的预期。8.2 监控与告警中的状态码应用状态码是监控的重要维度。你可以按状态码分类统计请求量2xx比例正常请求占比应该占绝大多数4xx比例客户端错误占比突然升高可能意味着有人在扫描或调用方代码有bug5xx比例服务端错误占比这是最关键的告警指标超过阈值就应该告警我个人的经验是5xx比例超过1%就应该关注超过5%就应该告警。4xx比例突然升高也值得关注可能是调用方出了问题。另外不同状态码的告警级别应该不同。500、502、503、504应该高优先级告警400、404可以低优先级或只记录不告警。8.3 排查问题时如何利用状态码排查线上问题时状态码是第一手线索。我的排查思路通常是先看状态码分布确定问题出在客户端还是服务端如果是5xx看具体是500、502、503还是504定位问题环节如果是4xx看是401、403、404还是429判断是认证、权限、路由还是限流问题结合访问日志和错误日志定位具体请求和堆栈举个例子如果突然出现大量504说明上游服务处理超时应该去查上游服务的慢查询或外部依赖。如果突然出现大量502说明上游服务可能挂了或响应格式不对应该去查上游服务的健康状态。8.4 常见误区与避坑指南误区一所有错误都返回200。这是最严重的误区直接破坏了HTTP协议的语义。监控、告警、客户端库全部失效。误区二401和403混用。未认证用401无权限用403别搞反了。误区三404和410混用。永久删除用410临时找不到用404。误区四500响应体暴露堆栈。安全风险攻击者可以利用堆栈信息找到漏洞。误区五重定向用302但期望浏览器缓存。302不会被缓存需要缓存用301。误区六忽略Retry-After头。429和503应该带Retry-After告诉客户端多久后重试。误区七405返回404。方法不支持应该返回405并带Allow头不是404。提示状态码的选择没有绝对的对错但一旦团队形成规范就应该严格遵守。一致性比“最优选择”更重要。9. 几个真实场景的状态码排查实录9.1 场景一接口偶发502的排查过程某次线上服务偶发502频率不高但持续存在。排查思路查看Nginx错误日志发现upstream sent invalid header错误定位到上游服务返回的响应头中包含非法字符进一步排查发现是某个业务字段被直接放进了响应头字段值包含换行符修复对响应头字段做过滤移除非法字符这个案例说明502不一定是服务挂了也可能是响应不符合网关预期。排查时要看网关的错误日志而不仅仅是上游服务的日志。9.2 场景二304缓存导致的样式不更新某次前端发版后部分用户反馈样式没更新。排查思路确认CDN和浏览器缓存都配置了304检查ETag生成逻辑发现是基于文件修改时间生成的发版时文件内容变了但修改时间没变构建工具的问题修复ETag改用文件内容哈希生成这个案例说明304缓存用好了是优化用不好就是坑。ETag的生成逻辑一定要可靠基于内容哈希比基于时间更安全。9.3 场景三429限流导致的调用方雪崩某次调用方反馈接口大量失败排查发现是429。原因是调用方没有处理429收到429后立即重试导致请求量翻倍触发更严格的限流。修复方案调用方增加指数退避重试逻辑服务端在429响应中明确返回Retry-After双方约定限流配额和重试策略这个案例说明429不是返回了就完事调用方必须正确处理。否则限流反而会加剧问题。10. 状态码速查与个人经验总结10.1 高频状态码速查表状态码含义典型场景注意事项200成功GET查询成功返回完整资源201已创建POST创建成功带Location头204无内容DELETE成功无响应体301永久重定向域名更换浏览器会缓存302临时重定向临时跳转不缓存304未修改缓存有效无响应体307临时重定向API迁移保持请求方法308永久重定向API永久迁移保持请求方法400请求错误格式错误返回具体错误401未认证未登录带WWW-Authenticate403无权限已登录但无权限不重新认证404不存在资源找不到友好错误页405方法不允许方法不对带Allow头409冲突并发更新返回冲突详情410已删除永久删除搜索引擎移除422语义错误字段校验失败返回字段错误429限流请求过多带Retry-After500服务器错误未处理异常不暴露堆栈502网关错误上游无效响应查上游日志503不可用维护或过载带Retry-After504网关超时上游超时查慢查询10.2 我个人的使用心得做了这么多年开发我对状态码最大的体会是它是HTTP协议里最被低估的部分。很多人觉得状态码就是几个数字背下来就行。但实际上状态码用得好不好直接反映了一个团队对HTTP协议的理解深度。我的建议是下次你写接口的时候花五分钟想想该用哪个状态码。创建用201删除用204校验失败用422限流用429。这些细节积累起来你的API就会变得自解释、易调试、好维护。还有一点状态码是给机器看的错误信息是给人看的。两者都要做好。状态码让客户端能自动化处理错误信息让开发者能快速定位问题。缺一不可。最后分享一个我踩过的坑曾经有个接口所有错误都返回200响应体里放{code: 500}。后来接入监控系统时发现所有请求都是200错误率永远是0。排查线上问题时完全看不出异常只能人工翻日志。后来花了整整一周把所有接口的状态码改对监控才真正发挥作用。状态码这件事早改早受益。