# 速率限制与配额

> 了解各个 Kanorio API 如何限制请求速率、哪些标头可供查询状态，以及限制存储资源的计划配额。

> Markdown version of https://kanorio.com/zh-CN/developers/basics/rate-limits. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/rate-limits.md

速率限制可防止单一集成拖慢其他服务。在 Management API 中，速率限制按令牌计算；而在公开 API 中，则按网站、访客或客户计算。配额则不同：它限制网站可存储的资源数量（例如集合项目或 Webhook 端点），并取决于您的计划。

## 当您达到限制时

API 会返回 `429` 状态码，并附带 `RATE_LIMITED` 错误代码以及以秒为单位的 `Retry-After` 标头。请至少等待该时间，然后重试（建议使用退避算法）。

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests.",
    "details": { "retryAfter": 12 }
  }
}
```

当后端繁忙而非请求过多时，部分操作会返回更具体的 `429` 错误代码，例如 `SEARCH_BUSY` 或 `ANALYTICS_BUSY`。请以相同方式处理这些情况。

## Management API

每个令牌都有各自的预算。大多数操作共享默认层级。由于分析查询较为耗费资源，因此每个令牌有较低的层级限制，且该网站上的所有令牌共享一个网站层级的上限。REST 与 MCP 调用均计入相同的预算中。

[Management API 参考文档](https://kanorio.com/en/developers/management-api)中的每项操作都会显示其层级，且 OpenAPI 文档会将其标记为 `x-kanorio-rate-limit`。

## Content Delivery API

从边缘缓存（Edge Cache）提供的响应不计入限制，因此若繁忙网站的缓存已预热，则不会达到这些限制。缓存未命中（Cache Misses）、表单写入、分析信标与草稿预览会计入令牌桶（Token Buckets）中：每个桶会以固定速率重新填充，并允许短时间的突发流量。计数的响应会包含以下标头：

| 标头 | 含义 |
|---|---|
| `X-RateLimit-Limit` | 存储桶大小 |
| `X-RateLimit-Remaining` | 当前剩余请求次数 |
| `X-RateLimit-Reset` | 距离存储桶恢复满额所需的秒数 |

请尽可能在您的服务器或构建阶段建立页面，并让边缘缓存处理访客流量。

## Customer API

已登录的调用受限于每个客户令牌。登录请求则受限于每个 IP 地址。

## 当前的限制与配额

以下数值是根据 API 强制执行的相同常量所产生。

### Management API tiers

| Tier | Limit | Applies to |
| --- | --- | --- |
| default | 120/minute per token | Every operation not listed below |
| heavy | 20/minute per token, plus 20/minute per site | Analytics queries (`analytics.*`); REST and MCP share the bucket |
| publish | 30/hour per token | Publishing and unpublishing |

### Content Delivery API buckets

Cache hits are not counted. Only requests that miss the edge cache, form writes and analytics beacons use these buckets.

| Bucket | Limit |
| --- | --- |
| Cache misses per site | 20 requests/second, burst 100 |
| Cache misses per visitor IP | 10 requests/second, burst 30 |
| Draft preview per IP | 2 requests/second, burst 20 |
| Gated content per customer token | 5 requests/second, burst 30 |

### Customer API buckets

| Bucket | Limit |
| --- | --- |
| Per customer token | 5 requests/second, burst 30 |
| Sign-in (challenge and verify) per IP | 1 requests/second, burst 10 |

### Plan quotas

| Resource | Free | Pro | Business |
| --- | --- | --- | --- |
| Collection items included | 50 | 1,000 | 10,000 |
| Storage included | 200 MB | 10 GB | 200 GB |
| Custom domains | 0 | 1 | 5 |
| Webhook endpoints per site | 10 | 10 | 10 |
| Rows per import batch | 100 | 1,000 | 2,000 |