HTTP 状态码快速参考
状态码、请求头、常见响应模式
信息 1xx
1xx 状态码
| 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 状态码
| 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 用法
| GET → 200 | 返回含资源体的响应 |
| POST → 201 | 资源已创建,包含 Location 头 |
| PUT → 200/204 | 已更新资源(含/不含响应体) |
| DELETE → 204 | 已删除,不返回响应体 |
| PATCH → 200 | 局部更新,返回已修改资源 |
重定向 3xx
3xx 状态码
| 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 — 保持原方法,永久位置 |
重定向行为
| 301/308 | 永久 — 搜索引擎更新索引 |
| 302/307 | 临时 — 原 URL 仍为标准 |
| 301/302 | 重定向后可能变更方法为 GET |
| 307/308 | 必须保持原 HTTP 方法 |
客户端错误 4xx
常见客户端错误
| 400 | Bad Request — 格式错误或参数无效 |
| 401 | Unauthorized — 需要认证或认证失败 |
| 403 | Forbidden — 已认证但无权限 |
| 404 | Not Found — 资源不存在 |
| 405 | Method Not Allowed — 不支持该 HTTP 方法 |
| 406 | Not Acceptable — 无法满足 Accept 头 |
| 408 | Request Timeout — 客户端发送请求过慢 |
| 409 | Conflict — 请求与当前状态冲突 |
更多客户端错误
| 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 状态码
| 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 — 需要门户登录 |
重试策略
| 500 | 带退避重试;可能是暂时性错误 |
| 502/504 | 重试 — 上游问题可能恢复 |
| 503 | 重试前检查 Retry-After 头 |
| 501/505 | 不重试 — 修复客户端请求 |
常用状态码
最常用状态码(速查)
| 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 — 稍后再试 |
请求头参考
请求头
| 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 | 客户端标识字符串 |
响应头
| 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
→ 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