返回知识库

数据与服务 · 网络与接口

HTTP 状态码Status Code

状态码是状态行里的 3 位数字,首位就是类别:2xx 成功、3xx 重定向、4xx 客户端要改、5xx 服务端要查;按类别决定继续、修正还是重试,失败绝不伪装成 200。

状态码回执台:同一订单,为什么是 201 或 422

先送出一张订单。完整请求创建资源并返回 201 与 Location;漏填地址则返回 422 和可定位的字段错误。状态行应如实告诉客户端下一步。

订单服务 · 一次请求,一张会改变的回执

POST/api/ordersbody: sku + address
HTTP/1.1 201 Created2xx:读取新资源
Location: /api/orders/842
{
  "data": { "id": "842", "status": "queued" },
  "error": null
}

资源已创建。客户端可读取 data,再跳到新订单地址。

判断依据与下一步:201 表示新资源已创建;读取 data,并沿 Location 进入订单。

首位即类别:五个数字段,五种动作

状态码是状态行里的 3 位数字,首位直接说明结果性质。看百位就能分流,是读、是跟随、是修正、还是重试。

类别服务器告诉你什么客户端下一步
1xx信息100 Continue请求已收到,客户端继续完成握手或等待。继续等待
2xx成功200 OK · 201 Created · 204 No Content服务器完成请求,响应可交给页面或调用方处理。读取结果
3xx重定向301 · 302 · 304 Not Modified资源位置或缓存策略要求客户端改变读取方式。跟随或用缓存
4xx客户端错400 · 401 · 403 · 404 · 422 · 429请求本身有问题:格式、身份、权限或资源状态需客户端修正。修正请求
5xx服务端错500 · 502 · 503 · 504服务器或上游依赖暂时无法完成请求,责任不在客户端。谨慎重试
离开后记住
  • 首位即类别:看百位就知道是成功、重定向、要修正、还是要重试。
  • 用户能改的错(4xx)和服务端要查的错(5xx)绝不能混。
  • 业务失败别返 200——否则 HTTP 层的缓存、重试、监控全部失效。
  • 只有 429、5xx 和网络瞬断才考虑重试,4xx 重发只会再错一次。

回执台先让你看见 2xx 与 4xx 的分流;1xx 在实际业务里很少亲手处理。读类别之后还要看方法、响应体、Location、Retry-After 和请求是否幂等——状态码是分流信号,不是跳过契约校验的捷径。

什么时候用哪个码

同样是「写完了」,建资源、更新资源、删除资源该返不同码;同样是「出错了」,用户能改和服务端要查绝不能混。

  • RESTful 选码新建资源返 201,更新返 200 加新值,删除或无内容返 204;通用成功才用 200。
  • 缓存与重定向浏览器缓存命中返 304,永久搬家 301,临时跳转 302;都靠 Location 或本地副本,不要把重定向链当成业务成功。
  • 客户端错 vs 服务端错4xx 是「客户端要改」:补字段、登录、补权限、改频率;5xx 是「服务端要查」:保留 request id,写操作还要防重复执行。
  • 重试边界429、502、503、504 和网络瞬断可对幂等请求按退避重试;4xx 除 408/429 外不要重试,重发只会再错一次。
  • 200 陷阱业务失败别返 200 加 body 错误——HTTP 层的缓存、重试、监控会全部失效,前端只能逐个判断。

正反例:语义化状态码 vs 全程 200

同一个「下单失败」接口,返回 422 还是 200,决定了前端、网关和监控能不能各司其职。

正例422 + 字段错误

前端按 4xx 知道是用户能改的错,保留输入、标红缺名称的输入框,提示「请填写项目名称」。

网关不会重试,监控也不会把它当成服务故障;同类错误能聚合出报表。

反例200 + {success:false}

HTTP 层看到的全是成功:CDN 照样缓存、重试逻辑不触发、告警不响;前端必须每个接口手写「if success」。

一旦有人忘了判断,用户看到的就是空白或脏数据;失败被静默吞掉,排查只能翻日志。

快速自测

前端删除一篇文章后,接口返 204 No Content,接下来该怎么处理最合适?

继续查证

术语的技术定义和行为以这些一手或权威资料为准。

下一步学

和本知识点经常一起出现的概念。