HTTP 状态码详解：常见状态码含义与使用场景

一、HTTP 状态码是什么？

HTTP 状态码是服务器对客户端请求的结果说明。
例如浏览器、App、前端页面或接口调用发送请求：

GET /api/users/123 HTTP/1.1

服务器会返回：

HTTP/1.1 200 OK

其中 200 就是状态码，表示请求成功。
状态码不是业务数据本身，而是对这次HTTP请求结果的概括。

二、状态码分类

三、1xx：信息响应

100 Continue

表示服务器已经收到请求头，客户端可以继续发送请求体。
常见于大文件上传前的确认机制。
例如客户端想上传一个很大的文件，先问服务器：

Expect: 100-continue

如果服务器返回：

100 Continue

客户端再继续上传文件内容。

101 Switching Protocols

表示服务器同意切换协议。
常见场景是 WebSocket。
客户端请求从HTTP协议升级为 WebSocket：

Upgrade: websocket

服务器返回：

101 Switching Protocols

表示协议切换成功。

四、2xx：成功状态码

200 OK

最常见的成功状态码。
表示请求成功，服务器返回了正常的结果。
常见场景：

GET /api/users

返回：

"users": []

适用于：

201 Created

表示资源创建成功。
常见于新增数据：

POST /api/users

请求体：

{
  "name": "TOM"
}

返回：

201 Created

通常表示服务器已经创建了一个新用户。
有时响应头会带上新资源地址：

Loocation: /api/users/123

202 Accepted

表示请求已被接受，但还没有处理完成。
适合异步任务。
例如：

POST /api/video/export

服务器返回：

202 Accepted

意思是导出任务已经提交，但视频还没有生成完。

204 No Content

表示请求成功，但响应体为空。
常见于删除成功：

DELETE /api/users/123

返回：

204 No Content

含义是删除成功，但服务器不返回额外内容。

五、3xx：重定向状态码

3xx 表示客户端需要访问另一个地址。

301 Moved Permanently

永久重定向。
表示资源地址永久改变。
例如：

http://example.com

永久跳转到：

https://example.com

搜索引擎会把旧地址权重转移到新地址。

302 Found

临时重定向。
表示这次请求临时跳转到另一个地址，但是原地址以后还可能继续使用。
常见于登录跳转：

GET /profile

如果未登录，服务器返回：

302 Found
Locatio: /login

浏览器会跳转到登录页。

304 Not Modified

表示资源没有变化，客户端可以使用缓存。
例如浏览器之前请求过一个图片或 JS 文件，再次请求时带上缓存标识：

If-None-Match: "abc123"

服务器判断文件没变，就返回：

304 Not Modified

这样浏览器就不用重新下载资源。

六、4xx：客户端错误

4xx 表示请求方向有问题，通常是参数、权限、路径、格式等错误。

400 Bad Request

请求格式错误或参数错误。
常见原因：

例如：

{
  "age": "abc"
}

如果 age 应该是数字，就可能返回：

400 Bad Request

401 Unauthorized

表示未认证
注意：401 不是 “没有权限”，而是 “还没有证明你是谁”。
常见场景：

GET /api/me
Authorization：Bearer invalid-token

返回：

401 Unauthorized

403 Forbidden

表示已认证，但没有权限。
也就是说，服务器知道你是谁，但你不能访问这个资源。
例如普通用户访问管理员接口：

GET /api/admin/users

返回：

403 Forbidden

401 和 403 的区别：

404 Not Found

表示资源不存在。
常见原因：

GET /api/users/999

如果用户不存在，可以返回：

404 Not Found

405 Method Not Allowed

表示请求方法不允许。
例如接口只支持 GET：

GET /api/users

但你发送了：

POST /api/users

服务器可能返回：

405 Method Not Allowed

409 Conflict

表示请求与当前资源状态冲突。
常见场景：

{
  "username": "tom"
}

如果 tom 已存在，可以返回：

409 Conflict

422 Unprocessable Entity

表示请求格式正确，但语义校验失败。
它和 400 比较接近，但更偏向 “业务校验失败”。
例如：

{
  "email": "not-an-email",
  "password": "123"
}

JSON 格式没问题，但邮箱格式不合法、密码太短，就可以返回：

422 Unprocessable Entity

常用于表单校验。

429 Too Many Requests

表示请求太频繁，被限流。
常见场景：

429 Too Many Requests
Retry-After: 60

表示 60 秒后再试。

七、5xx：服务端错误

5xx 表示请求本身可能没问题，但服务处理失败。

500 Internal Server Error

服务器内部错误。
常见原因：

TypeError: Cannot read property 'id' of undefined

就可能返回：

500 Inernal Server Error

502 Bad Gateway

网关错误。
通常发生在代理服务器、网关负载均衡器和上游服务之间。
例如：

浏览器 -> Nginx -> 后端服务

如果 Nginx 能收到请求，但后端服务返回了无效响应，可能返回：

502 Bad Gateway

常见原因：

503 Service Unavailable

服务不可用。
常见场景：

503 Service Unavailable

有时会带：

Retry-After: 300

表示 300 秒后再试。

504 Gateway Timeout

网关超时。
还是以 Nginx 为例：

浏览器 -> Nginx -> 后端服务

如果 Nginx 等后端响应等太久，超时后就返回：

504 Gateway Timeout

常见原因：

八、常见状态码对比

400、401、403、404的区别

500、502、503、504 的区别

九、接口设计时怎么选状态码？

查询成功

GET /api/users/123

用户存在：

200 OK

用户不存在：

404 Not Found

创建成功

POST /api/users

创建成功：

201 Created

用户名重复：

409 Conflict

参数格式错误：

400 Bad Request

业务校验失败：

422 Unprocessable Entity

更新成功

PUT /api/users/123

更新成功并返回数据：

200 OK

更新成功但不返回内容：

204 No Content

用户不存在：

404  Not Found

删除成功

DELETE /api/users/123

删除成功：

204 No Content

资源不存在：

404 Not Found

登录认证

未带 token：

401 Unauthorized

token 过期：

401 Unauthorized

权限不足：

403 Forbidden

前后端开发中的处理建议

前端处理

前端通常这样处理：

后端处理

后端应尽量做到：

{
  "code": "USER_NOT_FOUND",
  "message": "用户不存在",
  "details": {
    "userId": 123
  }
}

十一、常见误区

误区一：所有接口都返回 200

不推荐这样：

200 OK

{
  "success": false,
  "message": "用户不存在"
}

更推荐：

404 Not Found

{
  "code": "USER_NOT_FOUND",
  "message": "用户不存在"
}

原因是 HTTP 状态码本身就应该表达请求结果。

误区二：401 和 403 混用

正确区分：

没登录 / token 无效 -> 401
登录了但权限不够 -> 403

误区三：参数错误都用 500

参数错误是客户端问题，通常应该返回：

400 Bad Request

或者：

422 Unprocessable Entity

而不是：

500 Internal Server Error

误区四：后端异常信息直接返回前端

不推荐：

{
  "message": "SQLSyntaxErrorException: Table user_info not found"
}

推荐：

{
  "code": "INTERNAL_ERROR",
  "message": "服务器内部错误"
}

详细异常应记录到后端日志，而不是暴露给用户。

十二、速查表

核心判断逻辑：

请求成功了吗？
  是 -> 2xx
  否 -> 看是否需要跳转
        是 -> 3xx
        否 -> 是客户端问题？
              是 -> 4xx
              否 -> 5xx