HTTP 状态码一览
按类别整理了 Web 开发中常遇到的 HTTP 状态码，可用于 API 设计、调试与错误处理。
什么是 HTTP 状态码
HTTP 状态码是服务器针对客户端（浏览器或 API 客户端）请求返回的三位数字，用于表示响应状态。首位数字决定类别，共分 1xx～5xx 五类。返回恰当的状态码在 RESTful API 设计中非常重要。
1xx：信息响应（Informational）
表示请求已收到且仍在处理中。浏览器会自动处理，开发者很少直接接触。
| 状态码 | 名称 | 说明 |
|---|---|---|
100 | Continue | 已收到请求的第一部分，客户端可继续发送 |
101 | Switching Protocols | 接受协议切换请求，用于建立 WebSocket 连接 |
103 | Early Hints | 在最终响应之前提示客户端开始预加载资源 |
2xx：成功响应（Success）
表示请求已被正常接受并处理，是 API 开发中最常用的一类。
| 状态码 | 名称 | 说明 | 主要用途 |
|---|---|---|---|
200 | OK | 请求成功 | GET / PUT / PATCH 成功时 |
201 | Created | 请求成功且创建了新资源 | POST 成功创建资源时 |
202 | Accepted | 已接受请求但尚未处理完成 | 接受异步处理任务时 |
204 | No Content | 请求成功但无内容返回 | DELETE 成功，或 PUT 仅执行更新时 |
206 | Partial Content | 对范围请求的部分响应 | 大文件断点续传时 |
3xx：重定向（Redirection）
表示完成请求需要额外操作（通常是跟随重定向）。在 SEO 和 URL 迁移时尤为重要。
| 状态码 | 名称 | 说明 | 主要用途 |
|---|---|---|---|
301 | Moved Permanently | 资源已永久移动 | URL 变更、域名迁移，可继承 SEO 权重 |
302 | Found | 临时重定向到其他 URL | 维护期间的临时转发 |
303 | See Other | 使用 GET 方法访问另一个 URL | POST 处理后的重定向（PRG 模式） |
304 | Not Modified | 资源未发生变化 | 利用浏览器缓存，节省带宽 |
307 | Temporary Redirect | 临时重定向（保持请求方法） | HTTP→HTTPS 的临时转发 |
308 | Permanent Redirect | 永久重定向（保持请求方法） | API 端点的永久迁移 |
4xx：客户端错误（Client Error）
表示问题出在客户端，通常是请求内容或认证信息有误。
| 状态码 | 名称 | 说明 | 主要用途 |
|---|---|---|---|
400 | Bad Request | 请求语法不正确 | 校验错误、非法 JSON |
401 | Unauthorized | 需要认证 | 未登录、令牌过期 |
403 | Forbidden | 没有访问权限 | 已认证但无权访问该资源 |
404 | Not Found | 未找到资源 | 不存在的 URL、已删除的资源 |
405 | Method Not Allowed | 不允许的 HTTP 方法 | 向仅支持 GET 的端点发送 POST |
408 | Request Timeout | 请求超时 | 客户端发送数据过慢时 |
409 | Conflict | 资源冲突 | 重复数据写入、乐观锁冲突 |
413 | Payload Too Large | 请求体过大 | 超出文件上传上限 |
415 | Unsupported Media Type | 不支持的媒体类型 | 错误的 Content-Type |
422 | Unprocessable Entity | 语法正确但语义上无法处理 | 校验错误（含明细） |
429 | Too Many Requests | 超出速率限制 | API 调用次数限制 |
5xx：服务器错误（Server Error）
表示服务器端处理失败，通常是配置错误或应用程序缺陷。
| 状态码 | 名称 | 说明 | 主要用途 |
|---|---|---|---|
500 | Internal Server Error | 服务器内部错误 | 未捕获的异常、应用程序缺陷 |
501 | Not Implemented | 服务器不支持该功能 | 尚未实现的 API 端点 |
502 | Bad Gateway | 网关收到了无效响应 | 反向代理的上游服务器无法响应 |
503 | Service Unavailable | 服务不可用 | 维护中或负载过高 |
504 | Gateway Timeout | 网关超时 | 上游服务器响应超时 |
常见问题
401 与 403 有什么区别？
401 Unauthorized 表示需要认证，提示客户端登录或提供令牌。403 Forbidden 表示已认证但没有该资源的访问权限。例如普通用户访问管理员专用页面时应返回 403。
301 与 308 有什么区别？
两者都是永久重定向，但 301 在重定向过程中可能把 HTTP 方法改写为 GET，而 308 会保持原有请求方法。若希望 POST 重定向后仍为 POST，请使用 308。
遇到 413 错误怎么办？
上传时若返回 413 Payload Too Large，请逐层检查限制：Web 服务器（Nginx 的 client_max_body_size、Apache 的 LimitRequestBody）以及 PHP（upload_max_filesize、post_max_size）。可用 DevLab 的阈值测试文件验证实际上限。
❓ 常见问题
哪些状态码会影响 SEO？
传递权重的是 301 与 308；302 与 307 被视为临时，原 URL 会被保留。404 与 410 都会使页面退出索引，但 410 会更快停止重新抓取。503 被理解为临时故障，配合 Retry-After 可用于调节抓取频率。对不存在的页面返回 200 会被判定为软 404，并拖累质量评估。
4xx 与 5xx 分别是谁的责任？
4xx 指向请求方，重复同样的请求结果不会改变；5xx 指向服务端，过一段时间可能成功。这一区分直接决定重试设计：遇到 4xx 立即放弃并记录，遇到 5xx 用指数退避重试。例外是 429，它虽属 4xx，但应按 Retry-After 重试。
可以自定义状态码吗？
不要这么做。中间代理、CDN 与 HTTP 客户端按规范会把未知状态码当作同类的 x00 处理，499 会被当成 400。也就是说自定义码传不出去，细节也一并丢失。需要区分时请选择合适的标准码，把细节放进响应体（通常用 RFC 9457 的 Problem Details）。