# 速率限制與配額

> 了解各個 Kanorio API 如何限制請求速率、哪些標頭可供查詢狀態，以及限制儲存資源的計劃配額。

> Markdown version of https://kanorio.com/zh-HK/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 |