> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/cn/compute/aig/gateway-features/retry-control.md).

# 请求重试控制

## 1. 概述

`X-Zenlayer-Retry-Times` 是 Zenlayer 网关支持的自定义 HTTP 请求头，用于控制网关在后端请求异常时的重试行为。

通过该请求头，客户端可以精确控制 Zenlayer 网关是否对后端进行重试，以及最多重试的次数。

> 若不携带此请求头，或值不合法（非数字，或小于 0 的数字），Zenlayer 将使用自身的默认重试规则。

***

## 2. 请求说明

* **请求方法**：POST
* **请求地址**：

  > `https://gateway.theturbo.ai/$ANY_URI`

***

## 3. 请求参数

### 3.1 Header 参数

| 参数名称                     | 类型      | 必填 | 说明                                                                        | 示例值 |
| ------------------------ | ------- | -- | ------------------------------------------------------------------------- | --- |
| `X-Zenlayer-Retry-Times` | integer | 否  | 控制 Zenlayer 网关对后端的重试次数。`0` 表示不重试；大于 `0` 的整数表示首次异常后最多重试的次数。不传或值不合法时使用默认规则。 | `0` |

**取值说明：**

| 值          | 行为                    |
| ---------- | --------------------- |
| `0`        | 不重试，后端首次异常后直接返回错误响应   |
| 正整数（如 `3`） | 首次异常后最多重试 N 次（不含首次请求） |
| 未设置 / 不合法值 | 使用 Zenlayer 默认重试规则    |

> **不合法值**包括：非数字字符串（如 `abc`）、负数（如 `-1`）、小数（如 `1.5`）。

***

## 4. 请求示例

### 4.1 禁用重试

```http
POST /v1/messages HTTP/1.1
Host: gateway.theturbo.ai
Content-Type: application/json
X-Zenlayer-Retry-Times: 0
```

网关在后端首次请求失败后，立即返回错误，不进行任何重试。

***

### 4.2 允许最多重试 3 次

```http
POST /v1/messages HTTP/1.1
Host: gateway.theturbo.ai
Content-Type: application/json
X-Zenlayer-Retry-Times: 3
```

首次请求失败后，网关最多再重试 3 次，总请求次数最多为 4 次（1 次首次 + 3 次重试）。

***

### 4.3 使用默认重试策略

```http
POST /v1/messages HTTP/1.1
Host: gateway.theturbo.ai
Content-Type: application/json
```

不携带 `X-Zenlayer-Retry-Times` 请求头，网关按照自身默认规则处理重试。