速率限制與配額

速率限制可防止單一整合拖慢其他服務。在 Management API 中，速率限制是按權杖計算；而在公開 API 中，則是按網站、訪客或顧客計算。配額則不同：它限制網站可儲存的資源數量（例如集合項目或 Webhook 端點），並取決於您的方案。

當您達到限制時

API 會回傳 429 狀態碼，並附帶 RATE_LIMITED 錯誤代碼以及以秒為單位的 Retry-After 標頭。請至少等待該時間，然後再進行重試（建議使用退避演算法）。

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

當後端繁忙而非請求過多時，部分操作會回傳更具體的 429 錯誤代碼，例如 SEARCH_BUSY 或 ANALYTICS_BUSY。請以相同方式處理這些情況。

Management API

每個權杖都有各自的預算。大多數操作共享預設層級。由於分析查詢較為耗費資源，因此每個權杖有較低的層級限制，且該網站上的所有權杖共享一個網站層級的上限。REST 與 MCP 呼叫均計入相同的預算中。

Management API 參考文件中的每項操作都會顯示其層級，且 OpenAPI 文件會將其標記為 x-kanorio-rate-limit。

Content Delivery API

從邊緣快取（Edge Cache）提供的回應不計入限制，因此若繁忙網站的快取已預熱，則不會達到這些限制。快取未命中（Cache Misses）、表單寫入、分析信標與草稿預覽會計入權杖桶（Token Buckets）中：每個桶會以固定速率重新填充，並允許短時間的突發流量。計數回應會包含以下標頭：

請盡可能在您的伺服器或建置階段建立頁面，並讓邊緣快取處理訪客流量。

Customer API

已登入的呼叫受限於每個顧客權杖。登入請求則受限於每個 IP 位址。

當前的限制與配額

以下數值是根據 API 強制執行的相同常數所產生。

Management API tiers

Content Delivery API buckets

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

Customer API buckets

Plan quotas