一、状态码分类

HTTP状态码由三位数字组成，第一位表示类别。

类别 范围 含义
1xx 100-199 信息性状态码
2xx 200-299 成功状态码
3xx 300-399 重定向状态码
4xx 400-499 客户端错误
5xx 500-599 服务端错误

二、1xx 信息性状态码

100 Continue

客户端发送Expect: 100-continue请求头后，服务器确认可以继续发送请求体。

101 Switching Protocols

协议切换，如从HTTP升级到WebSocket。

103 Early Hints

服务器在最终响应前，预先发送一些资源提示。

三、2xx 成功状态码

200 OK

请求成功。

  • GET：获取资源成功
  • POST：创建资源成功
  • PUT：更新资源成功

201 Created

资源创建成功，通常用于POST请求。

响应中应包含Location头指向新资源。

202 Accepted

请求已接受但未处理完成，异步处理场景使用。

204 No Content

请求成功但无响应体返回。

用于DELETE操作或PUT操作不需要返回内容时。

206 Partial Content

范围请求成功，返回部分内容。

用于断点续传和大文件下载。

四、3xx 重定向状态码

301 Moved Permanently

永久重定向。

  • 搜索引擎更新URL
  • HTTP迁移到HTTPS
  • 浏览器缓存新地址

302 Found

临时重定向。

  • 临时维护页面跳转
  • 未登录跳转登录页

303 See Other

使用GET方法重定向到另一个URL。

通常在POST请求处理后，重定向到结果页面。

304 Not Modified

资源未修改，使用缓存。

配合If-Modified-Since或If-None-Match使用。

307 Temporary Redirect

临时重定向，保持原请求方法。

与302区别：307保证不改变请求方法。

308 Permanent Redirect

永久重定向，保持原请求方法。

与301区别：308保证不改变请求方法。

重定向对比

状态码 类型 请求方法
301 永久 可能变为GET
302 临时 可能变为GET
303 临时 变为GET
307 临时 不变
308 永久 不变

五、4xx 客户端错误

400 Bad Request

请求语法错误或参数无效。

常见原因：

  • 请求参数格式错误
  • JSON解析失败
  • 缺少必要参数

401 Unauthorized

未认证，需要登录。

与403区别：401是未认证，403是已认证但无权限。

403 Forbidden

已认证但无权限访问。

常见原因：

  • 权限不足
  • 资源被禁止访问
  • IP被限制

404 Not Found

请求的资源不存在。

常见原因：

  • URL错误
  • 资源已删除
  • 路由配置错误

405 Method Not Allowed

请求方法不被允许。

如对只支持GET的接口发送POST请求。

响应中包含Allow头列出支持的方法。

408 Request Timeout

请求超时，服务器等待客户端发送请求超时。

409 Conflict

请求冲突。

常见场景：

  • 创建已存在的资源
  • 并发修改冲突

410 Gone

资源已永久删除。

与404区别：410表示资源曾经存在但已删除，404表示不确定是否曾存在。

413 Payload Too Large

请求体过大。

服务器限制上传文件大小时返回。

415 Unsupported Media Type

不支持的媒体类型。

如服务器只接受JSON，但客户端发送XML。

422 Unprocessable Entity

请求格式正确但语义错误。

常见于参数校验失败。

429 Too Many Requests

请求过于频繁，触发限流。

响应中通常包含Retry-After头。

六、5xx 服务端错误

500 Internal Server Error

服务器内部错误。

常见原因：

  • 代码异常
  • 配置错误
  • 依赖服务故障

501 Not Implemented

服务器不支持请求的功能。

502 Bad Gateway

网关从上游服务器收到无效响应。

常见原因：

  • 上游服务不可用
  • Nginx转发到未启动的服务

503 Service Unavailable

服务暂不可用。

常见原因：

  • 服务器过载
  • 维护中
  • 熔断降级

响应中包含Retry-After头。

504 Gateway Timeout

网关等待上游服务器响应超时。

与408区别：504是网关等待上游超时，408是服务器等待客户端超时。

505 HTTP Version Not Supported

不支持的HTTP版本。

七、实际应用

RESTful API设计

操作 成功状态码 错误状态码
查询 200 404
创建 201 400, 409
更新 200 400, 404, 409
删除 204 404

错误响应格式

1
2
3
4
5
6
7
8
{
    "code": 400,
    "message": "参数校验失败",
    "details": [
        "name不能为空",
        "age必须大于0"
    ]
}

SpringBoot全局异常处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException e) {
        return ResponseEntity.badRequest()
            .body(new ErrorResponse(400, "参数校验失败"));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception e) {
        return ResponseEntity.internalServerError()
            .body(new ErrorResponse(500, "服务器内部错误"));
    }
}

八、总结

HTTP状态码要点：

  • 2xx：成功
  • 3xx：重定向
  • 4xx：客户端错误
  • 5xx：服务端错误

常用状态码：

  • 200：成功
  • 201：创建成功
  • 301/302：重定向
  • 400：请求错误
  • 401：未认证
  • 403：无权限
  • 404：不存在
  • 500：服务器错误
  • 502/503/504：网关和服务不可用

正确使用状态码可以让API语义清晰，便于前后端协作和问题排查。