> 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/api-introduction/instruction/ratelimits.md).

# 调用频率限制

为保障服务稳定性、防止滥用，Zenlayer Cloud API 对所有客户端的调用频率做了限制。当请求超出任一限制时，服务端会返回 HTTP `429 Too Many Requests` 及错误码 `REQUEST_LIMIT_EXCEEDED`。

## 限额

| 维度                  | 限额        |
| ------------------- | --------- |
| 单个来源 IP             | 5,000 次/秒 |
| 单个产品服务 × 单个账号（Team） | 50 次/秒    |
| 单个读接口 × 单个账号（Team）  | 40 次/秒    |
| 单个写接口 × 单个账号（Team）  | 20 次/秒    |

所有维度同时生效，请求需满足全部限额。

> **读接口 vs. 写接口** — 读接口为查询类操作（如 `Describe*`、`List*`）；写接口为变更资源状态的操作（如 `Create*`、`Delete*`、`Update*`）。
>
> 同一账号（Team）下所有访问凭证（AccessKey、Token）共享账号维度的限额。

## 响应头

| 响应头                     | 说明                              |
| ----------------------- | ------------------------------- |
| `X-RateLimit-Limit`     | 当前窗口内的最大请求数                     |
| `X-RateLimit-Remaining` | 当前窗口内剩余可用请求数                    |
| `Retry-After`           | **（仅 429 时返回）** 建议等待的秒数，到期后方可重试 |

## 处理 429 响应

请求触发限流时，服务端返回：

* HTTP 状态码：`429 Too Many Requests`
* 响应体：

```json
{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "code": "REQUEST_LIMIT_EXCEEDED",
  "message": "Too many requests, please try again later"
}
```

`REQUEST_LIMIT_EXCEEDED` 已收录在[公共错误码](/api-reference/cn/api-introduction/instruction/commonerrorcode.md)中。

收到 `429` 后，请先读取 `Retry-After` 响应头并等待相应秒数再重试。建议同时采用**指数退避**策略：

| 项      | 推荐值          |
| ------ | ------------ |
| 最大重试次数 | 3 次          |
| 退避序列   | 1s → 2s → 4s |

对于读密集或高频场景，建议在业务侧合并请求、使用客户端缓存或异步化处理。

## SDK 支持

Zenlayer 官方 SDK（Go / Java / Python）已默认内置上述限流重试逻辑，详见各 SDK README 的配置说明。

## 申请更高限额

如业务确有更高 QPS 需求，请通过工单或商务渠道联系 Zenlayer，提供账号 CID、预计调用峰值及业务场景说明。