# HTTP 状态码快速参考

*状态码、请求头、常见响应模式*

> Source: HTTP/1.1 Specification (RFC 9110) · MIT

## 信息 1xx

### 1xx 状态码

| Command | Description |
|---------|-------------|
| `100` | Continue — 服务端已收到头，客户端应发送请求体 |
| `101` | Switching Protocols — 升级到 WebSocket 或 HTTP/2 |
| `102` | Processing — 服务端收到请求，仍在处理（WebDAV） |
| `103` | Early Hints — 最终响应前预加载资源 |

### 使用说明

```
# 100 Continue: client sends Expect header, waits for 100
curl -H "Expect: 100-continue" -d @large.json URL
# 101: upgrade to WebSocket
Connection: Upgrade / Upgrade: websocket
```

## 成功 2xx

### 2xx 状态码

| Command | Description |
|---------|-------------|
| `200` | OK — 标准成功响应 |
| `201` | Created — 资源创建成功（POST/PUT） |
| `202` | Accepted — 请求已收到，异步处理中 |
| `203` | Non-Authoritative Info — 经代理转换 |
| `204` | No Content — 成功但无响应体（DELETE） |
| `205` | Reset Content — 成功，客户端应重置表单 |
| `206` | Partial Content — 范围请求已完成 |
| `207` | Multi-Status — 多个状态码（WebDAV） |

### REST API 用法

| Command | Description |
|---------|-------------|
| `GET → 200` | 返回含资源体的响应 |
| `POST → 201` | 资源已创建，包含 Location 头 |
| `PUT → 200/204` | 已更新资源（含/不含响应体） |
| `DELETE → 204` | 已删除，不返回响应体 |
| `PATCH → 200` | 局部更新，返回已修改资源 |

## 重定向 3xx

### 3xx 状态码

| Command | Description |
|---------|-------------|
| `300` | Multiple Choices — 有多种表示可用 |
| `301` | Moved Permanently — 资源已永久移动，请更新书签 |
| `302` | Found — 临时重定向（常被误用为 303） |
| `303` | See Other — POST 后用 GET 重定向 |
| `304` | Not Modified — 使用缓存版本（ETag/If-Modified） |
| `307` | Temporary Redirect — 保持原方法，临时位置 |
| `308` | Permanent Redirect — 保持原方法，永久位置 |

### 重定向行为

| Command | Description |
|---------|-------------|
| `301/308` | 永久 — 搜索引擎更新索引 |
| `302/307` | 临时 — 原 URL 仍为标准 |
| `301/302` | 重定向后可能变更方法为 GET |
| `307/308` | 必须保持原 HTTP 方法 |

## 客户端错误 4xx

### 常见客户端错误

| Command | Description |
|---------|-------------|
| `400` | Bad Request — 格式错误或参数无效 |
| `401` | Unauthorized — 需要认证或认证失败 |
| `403` | Forbidden — 已认证但无权限 |
| `404` | Not Found — 资源不存在 |
| `405` | Method Not Allowed — 不支持该 HTTP 方法 |
| `406` | Not Acceptable — 无法满足 Accept 头 |
| `408` | Request Timeout — 客户端发送请求过慢 |
| `409` | Conflict — 请求与当前状态冲突 |

### 更多客户端错误

| Command | Description |
|---------|-------------|
| `410` | Gone — 资源已永久删除（不只是找不到） |
| `411` | Length Required — 缺少 Content-Length 头 |
| `412` | Precondition Failed — If-Match/If-Unmodified 失败 |
| `413` | Content Too Large — 请求体超出限制 |
| `414` | URI Too Long — URL 超出服务器限制 |
| `415` | Unsupported Media Type — Content-Type 不被接受 |
| `422` | Unprocessable Content — 语法合法但语义错误 |
| `429` | Too Many Requests — 超出频率限制 |

## 服务器错误 5xx

### 5xx 状态码

| Command | Description |
|---------|-------------|
| `500` | Internal Server Error — 服务端未处理的异常 |
| `501` | Not Implemented — 服务端不支持该方法 |
| `502` | Bad Gateway — 上游服务器返回无效响应 |
| `503` | Service Unavailable — 过载或维护中 |
| `504` | Gateway Timeout — 上游服务器未及时响应 |
| `505` | HTTP Version Not Supported — 不支持该版本 |
| `507` | Insufficient Storage — 无法存储请求（WebDAV） |
| `511` | Network Auth Required — 需要门户登录 |

### 重试策略

| Command | Description |
|---------|-------------|
| `500` | 带退避重试；可能是暂时性错误 |
| `502/504` | 重试 — 上游问题可能恢复 |
| `503` | 重试前检查 Retry-After 头 |
| `501/505` | 不重试 — 修复客户端请求 |

## 常用状态码

### 最常用状态码（速查）

| Command | Description |
|---------|-------------|
| `200` | OK — 一切正常 |
| `201` | Created — 新资源已创建 |
| `204` | No Content — 成功，无响应体 |
| `301` | Moved Permanently — 更新 URL |
| `304` | Not Modified — 使用缓存 |
| `400` | Bad Request — 修复请求 |
| `401` | Unauthorized — 先登录 |
| `403` | Forbidden — 权限不足 |
| `404` | Not Found — URL 错误或已删除 |
| `422` | Unprocessable — 验证错误 |
| `429` | Too Many Requests — 降速 |
| `500` | Server Error — 不是你的问题 |
| `502` | Bad Gateway — 代理/上游故障 |
| `503` | Unavailable — 稍后再试 |

## 请求头参考

### 请求头

| Command | Description |
|---------|-------------|
| `Accept` | 期望的响应媒体类型（如 application/json） |
| `Authorization` | 凭证（Bearer token、Basic base64） |
| `Content-Type` | 请求体的媒体类型 |
| `If-None-Match` | 条件请求：用于缓存验证的 ETag |
| `If-Modified-Since` | 条件请求：用于缓存验证的日期 |
| `Cache-Control` | 缓存指令（no-cache、max-age） |
| `User-Agent` | 客户端标识字符串 |

### 响应头

| Command | Description |
|---------|-------------|
| `Content-Type` | 响应体的媒体类型 |
| `Location` | 重定向目标或已创建资源的 URL |
| `ETag` | 用于缓存验证的实体标签 |
| `Cache-Control` | 缓存指令（max-age、no-store） |
| `Retry-After` | 重试等待时间（429/503） |
| `WWW-Authenticate` | 所需认证方案（随 401 发送） |
| `Set-Cookie` | 在客户端设置 Cookie |

## 常用模式

### 缓存流程

```
# First request — server returns ETag
GET /api/data → 200, ETag: "abc123"
# Subsequent request — conditional
GET /api/data, If-None-Match: "abc123"
→ 304 Not Modified (use cache)
```

### 认证流程

```
# Unauthenticated request
GET /api/secret → 401, WWW-Authenticate: Bearer
# With token
GET /api/secret, Authorization: Bearer <token>
→ 200 OK
```

### 频率限制

```
# Rate limited response
429 Too Many Requests
Retry-After: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000
```

### 内容协商

```
# Client prefers JSON, accepts XML
Accept: application/json, application/xml;q=0.9
# Server can't satisfy → 406 Not Acceptable
# Server returns best match → 200 + Content-Type
```