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

# Rate Limits

To ensure service stability and prevent abuse, Zenlayer Cloud API enforces request rate limits on all clients. When a request exceeds any limit, the server returns HTTP `429 Too Many Requests` with error code `REQUEST_LIMIT_EXCEEDED`.

## Limits

| Dimension              | Limit                     |
| ---------------------- | ------------------------- |
| Per IP address         | 5,000 requests per second |
| Per service per Team   | 50 requests per second    |
| Per read API per Team  | 40 requests per second    |
| Per write API per Team | 20 requests per second    |

All limits apply simultaneously. A request must satisfy every dimension.

> **Read vs. write APIs** — Read APIs are query operations (e.g., `Describe*`, `List*`). Write APIs mutate state (e.g., `Create*`, `Delete*`, `Update*`).
>
> All credentials (AccessKey, Token) under the same Team share Team-scoped quotas.

## Response Headers

| Header                  | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `X-RateLimit-Limit`     | The maximum number of requests allowed in the current window |
| `X-RateLimit-Remaining` | The number of requests remaining in the current window       |
| `Retry-After`           | *(429 only)* Seconds to wait before retrying                 |

## Handling a 429 Response

When a request is rate-limited, the server returns:

* HTTP status: `429 Too Many Requests`
* Response body:

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

`REQUEST_LIMIT_EXCEEDED` is also listed in the [Common Error Codes](/api-reference/api-introduction/instruction/commonerrorcode.md).

Upon receiving a `429`, check the `Retry-After` header and wait at least that many seconds before retrying. We recommend **exponential backoff** as an additional safeguard:

| Setting          | Recommended value |
| ---------------- | ----------------- |
| Max retries      | 3                 |
| Backoff schedule | 1 s → 2 s → 4 s   |

For read-heavy or high-frequency workloads, consider request batching, client-side caching, or asynchronous processing.

## SDK Support

The official Zenlayer SDKs (Go / Java / Python) handle rate-limit retries automatically with the parameters above. See the SDK README for configuration options.

## Requesting a Higher Limit

If your workload requires a higher rate, contact Zenlayer via support ticket or your account manager with your CID, expected peak rate, and use case description.