# 状态码：5xx 服务端错误

> 500–511 的触发条件，以及 502/503/504 在网关场景下的判定边界。

- 作者：David（道雾轩）
- 专栏：HTTP/1.1 协议详解（https://daiw.org/manual/http11.md）
- 最后更新：2026-07-26
- 原文：https://daiw.org/manual/http11/status-5xx
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

5xx 表示**服务端知道自己出错或无法完成**请求。除响应 `HEAD` 外 **SHOULD** 带解释体。

关键性质：客户端**无需修改请求**即可重试（前提是方法幂等）——这与 4xx 相反。

## 500 Internal Server Error

服务端遇到意外情况，无法完成。**兜底码**：所有未归类的服务端异常都落在这里。

- 不应用它表达可归类的错误（`503` 过载、`504` 上游超时都有专码）。
- **默认不可缓存**。
- 生产中不得向外泄露堆栈——错误详情写日志，响应体只给相关 ID。

## 501 Not Implemented

服务端**不支持该请求所需的功能**，通常指方法本身未实现。

- **默认可缓存**（在可缓存码列表中）——这点常被忽略。
- 与 `405` 的区别见[方法](https://daiw.org/manual/http11/methods)：`501` 是「这方法我不会」，`405` 是「这方法我会，但这资源不给用」。

## 502 Bad Gateway

**网关/代理**从上游收到**无效响应**。

判定边界：上游**有响应但不合法**（协议错误、连接被重置、TLS 握手失败）。若上游根本没在规定时间内响应，那是 `504`。

## 503 Service Unavailable

服务端**当前**无法处理，通常因过载或停机维护，且**是暂时的**。

- **SHOULD** 带 `Retry-After`（`delay-seconds` 或 `HTTP-date`）。
- 默认不可缓存，但**可**被显式缓存指令覆盖。
- 语义明确暗示「稍后会恢复」——永久下线应用 `410` 或 `404`。
- 负载均衡健康检查失败、限流熔断打开时应返回此码，而非 `500`。

## 504 Gateway Timeout

网关/代理**未能在时限内**从上游获得响应。

与 `502` 的区别：`504` = 等不到；`502` = 等到了但不对。两者都发生在中间节点，不是源站自身的错误。

## 505 HTTP Version Not Supported

服务端不支持请求的**主版本号**。

- 响应 **SHOULD** 说明支持哪些版本。
- 收到 `HTTP/1.9` 这类同主版本的高次版本号时**不应**返回此码——应按 `HTTP/1.1` 处理（见[请求行](https://daiw.org/manual/http11/request-line)）。

## 506 Variant Also Negotiates

RFC 2295（透明内容协商）。服务端配置错误：被选中的变体自身又是可协商资源，形成循环。极罕见。

## 507 / 508

- `507 Insufficient Storage`（RFC 4918）：WebDAV，存储空间不足以完成操作。
- `508 Loop Detected`（RFC 5842）：WebDAV，处理中检测到无限循环。

## 510 Not Extended

RFC 2774（HTTP 扩展框架）。请求缺少服务端要求的扩展声明。该 RFC 为实验性，实际无部署。

## 511 Network Authentication Required

RFC 6585。客户端需**先通过网络接入认证**（强制门户 / captive portal）才能上网。

关键约束：

- **必须由拦截代理生成**，源服务器不应发送。
- 响应体应含指向登录页的链接，但**不得**用 `Location` 重定向——那会污染客户端对原目标 URI 的认知。
- 设计意图是让客户端（尤其是非浏览器程序）能**机器可读地**识别「我被强制门户拦了」，而不是把登录页误当成 API 响应。

## 5xx 与重试

| 码 | 幂等方法可自动重试 | 建议退避 |
| --- | --- | --- |
| `500` | ⚠️ 谨慎（可能是确定性 bug，重试无用） | 指数退避 |
| `502` | ✅ | 指数退避 + 抖动 |
| `503` | ✅ | **遵循 `Retry-After`** |
| `504` | ⚠️ 上游可能已执行——非幂等禁止重试 | 指数退避 |

`504` 的隐患：网关超时不代表上游没执行。对 `POST` 而言，超时后重试可能造成重复副作用——必须用幂等键去重。

本部分结束。下一部分从[表示与内容字段](https://daiw.org/manual/http11/representation-fields)开始，逐组解析字段。