状态码:5xx 服务端错误
500–511 的触发条件,以及 502/503/504 在网关场景下的判定边界。
作者 David更新于 第 11 篇(共 22 篇)
5xx 表示服务端知道自己出错或无法完成请求。除响应 HEAD 外 SHOULD 带解释体。
关键性质:客户端无需修改请求即可重试(前提是方法幂等)——这与 4xx 相反。
500 Internal Server Error
服务端遇到意外情况,无法完成。兜底码:所有未归类的服务端异常都落在这里。
- 不应用它表达可归类的错误(
503过载、504上游超时都有专码)。 - 默认不可缓存。
- 生产中不得向外泄露堆栈——错误详情写日志,响应体只给相关 ID。
501 Not Implemented
服务端不支持该请求所需的功能,通常指方法本身未实现。
- 默认可缓存(在可缓存码列表中)——这点常被忽略。
- 与
405的区别见方法: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处理(见请求行)。
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 而言,超时后重试可能造成重复副作用——必须用幂等键去重。
本部分结束。下一部分从表示与内容字段开始,逐组解析字段。