状态码: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 而言,超时后重试可能造成重复副作用——必须用幂等键去重。

本部分结束。下一部分从表示与内容字段开始,逐组解析字段。

本页目录