> 9.0 起 Elasticsearch 的超时异常从 5xx 变成 429（Too Many Requests）。这条 breaking change 不报错、不改数据，但会让"按 5xx 判服务端故障"的客户端、告警规则和重试逻辑全部误判。

## **说明**

本文描述问题及解决方法同样适用于 [腾讯云 Elasticsearch Service（ES）](https://cloud.tencent.com/document/product/845)。

## 结论先说

一个状态码的改动，影响面比看起来大：

* 客户端里 `if (status >= 500) 判定服务端故障` 的逻辑，从此**不再覆盖超时**；
* 反过来，把 429 一律当成"被限流、等一会儿再试"的代码，现在会把**等待超时**也当成限流；
* 告警规则如果按 5xx 计数，"集群里超时变多"这件事会从监控里**消失**。

这条改动官方只有一句话，没有细节，所以我直接去源码里对了一遍。

## 官方依据

9.0 的 breaking changes 列表里这一条（[docs/release-notes/breaking-changes.md @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/release-notes/breaking-changes.md)）：

```
304: * Change Elasticsearch timeouts to 429 response instead of 5xx [#116026]
```

`v9.4.2:docs/release-notes/breaking-changes.md#L304`——就这一行，没给原因也没给范围。所以下面全靠代码核实。

## 代码石锤：8.18 和 9.4.2 逐行对照

超时异常是 `ElasticsearchTimeoutException`。先看 **8.18**（[server/src/main/java/org/elasticsearch/ElasticsearchTimeoutException.java @ v8.18.0](https://github.com/elastic/elasticsearch/blob/v8.18.0/server/src/main/java/org/elasticsearch/ElasticsearchTimeoutException.java)）:

```java
public class ElasticsearchTimeoutException extends ElasticsearchException {
    public ElasticsearchTimeoutException(StreamInput in) throws IOException { super(in); }
    public ElasticsearchTimeoutException(Throwable cause) { super(cause); }
    public ElasticsearchTimeoutException(String message, Object... args) { super(message, args); }
    public ElasticsearchTimeoutException(String message, Throwable cause, Object... args) {
        super(message, cause, args);
    }
}
```

**没有覆写 `status()`**——所以它继承 `ElasticsearchException.status()` 的默认值，也就是 500（INTERNAL_SERVER_ERROR）。这就是"以前是 5xx"的来源。

再看 **9.4.2**（[同文件 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/ElasticsearchTimeoutException.java)）：

```java
40:    public RestStatus status() {
42:        return RestStatus.TOO_MANY_REQUESTS;
43:    }
46:    public boolean isTimeout() {
```

两个变化：

* 第 40–42 行：显式覆写 `status()`，返回 `RestStatus.TOO_MANY_REQUESTS`；
* 第 46 行：新增 `isTimeout()`，让调用方能直接判断"这是超时"，不用去猜状态码。

`TOO_MANY_REQUESTS` 的定义在 `v9.4.2:server/src/main/java/org/elasticsearch/rest/RestStatus.java#L468`：`TOO_MANY_REQUESTS(429)`——这个枚举值 8.18 和 9.4.2 里都有（同样在 468 行），变的只是超时异常不再走默认 500。

## 为什么是 429

官方没说，我的判断是**语义归位**：超时是"服务端在规定时间内没干完"，属于可重试的临时状态，和限流（429 Too Many Requests，标准语义里就带"你可以稍后重试"）是一类；而 5xx 的语义是"服务端出错"，客户端通常不会重试，还会把它算进故障率。以前把超时归到 5xx，等于让一堆可重试的场景被当成故障。

需要说明：这段是我的推断，不是官方文档的说法，判断依据是 HTTP 状态码的语义分工——**结论本身（5xx→429）是核实过的，原因是我补的解释**。

## 哪些路径会拿到 429

凡是抛 `ElasticsearchTimeoutException` 的地方，HTTP 状态码都从 5xx 变成 429。我在 `v9.4.2` 里 grep 了这个异常的引用位置，能核实到的有：

| 文件 | 场景 |
|---|---|
| `org/elasticsearch/action/support/ListenerTimeouts.java` | 请求 listener 的超时控制 |
| `org/elasticsearch/action/support/SubscribableListener.java` | listener 超时 |
| `org/elasticsearch/cluster/service/ClusterApplierRecordingService.java`（L103） | 集群状态应用没在规定时间完成 |
| `org/elasticsearch/action/admin/cluster/configuration/TransportAddVotingConfigExclusionsAction.java` | 投票配置排除的等待超时 |
| `org/elasticsearch/action/admin/cluster/configuration/TransportClearVotingConfigExclusionsAction.java` | 同上，清理分支 |
| `org/elasticsearch/action/fieldcaps/TransportFieldCapabilitiesAction.java` | `field_caps` 等待超时 |
| `org/elasticsearch/action/support/single/shard/TransportSingleShardAction.java` | 单分片操作（get、termvectors 一类） |
| `org/elasticsearch/common/util/concurrent/FutureUtils.java` | 通用 future 超时 |

**一条重要的边界**：搜索请求自带的 `timeout` 参数（以及 `search.default_search_timeout`）不在这个异常的抛出路径上——我 grep `action/search/` 目录没有命中 `ElasticsearchTimeoutException`，搜索超时的表现是返回已经收集到的部分结果、响应里带 `timed_out: true`，HTTP 状态码仍是 200。

这条我没有逐个接口实测，落到你的具体场景上，建议用一个真实超时请求确认一次，别照抄。

## 客户端要改什么

**1. 判断逻辑从"5xx 即故障"改成"先看是不是超时"。** 服务端现在给了更准的信号：

```json
{
  "error": { "type": "timeout_exception", "reason": "..." },
  "status": 429
}
```

判断顺序建议是：先判 `status == 429`，再看 `is_timeout` / 异常类型是不是 `timeout_exception`，最后才落到通用 5xx 分支。

**2. 重试策略要分开。** 超时和限流都是 429，但处置方式不一样：

* **限流**（`EsRejectedExecutionException`，见下节）：退避重试，同时该考虑降压；
* **超时**：重试是有用的，但先确认超时阈值合不合理——一直超时的重试只会把压力放大。

**3. 告警规则要补一个维度。** 如果告警是按 HTTP 状态码分桶的，超时会从 5xx 桶里消失、混进 429 桶（和限流一起）。建议把 429 拆成"限流 429"和"超时 429"两个指标再设阈值，否则限流告警会被超时稀释。

## 429 撞车了：怎么和限流区分

同一个 429 现在代表两件事，这是升级后最容易踩的坑。看 `v9.4.2:server/src/main/java/org/elasticsearch/ExceptionsHelper.java#L88-L89`：

```java
} else if (t instanceof EsRejectedExecutionException) {
    return RestStatus.TOO_MANY_REQUESTS;
}
```

也就是说，**队列打满被拒绝**（`EsRejectedExecutionException`）一直是 429，现在超时也变成 429。区分办法是看 `error.type`：

| 场景 | 异常类 | `error.type` |
|---|---|---|
| 被限流/队列满 | `EsRejectedExecutionException` | `es_rejected_execution_exception` |
| 等待超时 | `ElasticsearchTimeoutException` | `timeout_exception` |

别只看状态码。

## 写在最后

* **这条 breaking change 的杀伤力在于它很安静**：没有报错、没有数据影响，只是状态码语义变了，所以升级后没人第一时间发现，直到告警曲线和重试行为开始对不上。
* **改客户端的三件事**：判断顺序先 429 后 5xx、重试策略把超时和限流分开、告警把 429 拆成两个指标。
* **别忘了一条边界**：搜索的 `timeout` 不在这次改动里，它照旧返回 200 + `timed_out: true`。

## 参考

- [docs/release-notes/breaking-changes.md#L304 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/release-notes/breaking-changes.md)
- [ElasticsearchTimeoutException.java#L40-L46 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/ElasticsearchTimeoutException.java)
- [ElasticsearchTimeoutException.java @ v8.18.0（对照：未覆写 status）](https://github.com/elastic/elasticsearch/blob/v8.18.0/server/src/main/java/org/elasticsearch/ElasticsearchTimeoutException.java)
- [RestStatus.java#L468 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/rest/RestStatus.java)
- [ExceptionsHelper.java#L88-L89 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/ExceptionsHelper.java)

> 本文所有代码引用均取自本地 `elasticsearch/` 仓库 `v9.4.2` / `v8.18.0` 标签，行号已逐条核对。"为什么改成 429"一节是我的推断，已标明；"搜索 timeout 不受影响"一条未逐个接口实测，已在正文提示。


9.0 起 Elasticsearch 的超时异常从 5xx 变成 429（Too Many Requests）。这条 breaking change 不报错、不改数据，但会让"按 5xx 判服务端故障"的客户端、告警规则和重试逻辑全部误判。

超时不再是 5xx：ES 9.0 把它改成了 429，重试逻辑得跟着改

9.0 起 Elasticsearch 的超时异常从 5xx 变成 429（Too Many Requests）。

官方产研

云计算

后端

大数据

Elasticsearch 9.0起超时异常从5xx改为429状态码，影响客户端故障判定、重试逻辑和告警规则。通过源码对比8.18与9.4.2确认变更细节，429现同时代表限流和超时，需通过error.type区分。搜索timeout仍返回200+timed_out。提供客户端判断顺序、重试策略和告警拆分建议，适用于腾讯云ES。

Elasticsearch 

代码解释

Java

2026上云采购 | AI焕新·智启新局

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Elasticsearch 9.0起超时异常从5xx改为429状态码，影响客户端故障判定、重试逻辑和告警规则。通过源码对比8.18与9.4.2确认变更细节，429现同时代表限流和超时，需通过error.type区分。搜索timeout仍返回200+timed_out。提供客户端判断顺序、重试策略和告警拆分建议，适用于腾...

超时不再是 5xx：ES 9.0 把它改成了 429，重试逻辑得跟着改-腾讯云开发者社区-腾讯云

超时不再是 5xx：ES 9.0 把它改成了 429，重试逻辑得跟着改

超时不再是 5xx：ES 9.0 把它改成了 429，重试逻辑得跟着改

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐