配額與速率限制
每個組織一張帳單
Platform 使用量按組織而不是按 key 計量 — 您組織擁有的所有 key 都會消耗同一個 shared monthly budget，並共同受 rate-limit。一個 key、一張帳單：AI、maps 與 design 都從同一個 org meter 扣除。
budget 按每月日曆週期重設。
您的方案包含什麼
組織的 plan 同時決定 key 可存取的範圍與 shared monthly token budget：
| Plan | API surface | Monthly API tokens | Monthly map loads |
|---|---|---|---|
| Free | 僅 Basemaps — 具有 maps scope 與 tile product 的 publishable key | n/a（無 ai scope） | 50,000 |
| Pro | 完整 platform（ai, maps, design; browser + server keys） | 5,000,000 | 50,000 |
| Enterprise | 完整 platform | 50,000,000 | 50,000 |
所有 plan 都具有相同的 map-loads allowance — plan 的差異在於 tokens、API surface 與功能。Enterprise 超過 allowance 的 volume 是 按組織額外提高，而不是更高一級 plan。
Free-plan key 提供 basemap embed，並按 map loads 而不是 tokens 計量。如需存取 AI 與 design surface，請前往 kaleidr.com/billing 升級。plan 變更會在幾分鐘內套用至 現有 key，不需要 re-mint — 但在 Free 上 mint 的 key 會在下次 rotate 時 重新設定 scope。
429 body
會超過 cap 的 request 會傳回 429 Too Many Requests 與
flat top-level body — structured 429 payload 不會將欄位包在
detail object 中（只有 map_load_hard_stop 這類 string-detail 429 會這麼做）：
{
"error": "b2b.tokens_exceeded",
"meter": "b2b.tokens",
"tier": "pro",
"limit": 5000000,
"used": 5000000,
"remaining": 0,
"reset_at": "2026-10-01T00:00:00Z",
"reset_in_seconds": 123456
}
對 streaming endpoint，cap 也會在 stream 中透過
quota SSE event 顯示，讓 UI 能在 stream 結束前
作出反應。
flat 429 與 wrapped 429 的完整差異請參閱 Errors — Envelope。
超過 allowance
超過 allowance 後的行為取決於 plan，而且兩種情況刻意 設計得不同。
Free 會在達到 allowance 時停止。任何會超過它的 request 都會傳回
429 map_load_quota_exceeded。這個邊界就是 free basemap product。
Pro 與 Enterprise 會繼續提供服務。付費 account 的 overage 屬於 billing 問題， 而不是 outage，因此 embed 不會在月中突然停止 — 我們會 記錄 overage 並後續處理。
但這種寬限並非無限制。付費 plan 會在 allowance 的 5 倍處使用
429 map_load_hard_stop 停止。正常 embed 不會達到這一點；這個 ceiling
是為了防止有人從 page source 複製 publishable key 後
以您的名義產生無限制帳單。購買 map-load pack 會提高
allowance，ceiling 也會隨之提高。
如果經常進入 soft band，您需要的是更多 allowance，而不是 workaround — 聯絡我們。
Basemap access
designed basemaps 屬於您的 Kaleidr account，
不是 standalone public tile API：<kaleidr-map> embed 與 SDK 透過
publishable key（maps scope）授權，每次 map load — shared-map 開啟、
published/embedded view 或 SDK basemap session，大約 20 個 tile
request — 都會從上述 shared monthly allowance 中扣除。第三方在 keyed embed 外直接使用 tile.kaleidr.com 會被
429 與以下 body 阻擋：
{
"error": "tile_access_restricted",
"message": "Direct access to tile.kaleidr.com requires a Kaleidr account. Kaleidr-hosted maps and embeds are unaffected — see the docs.",
"docs": "https://docs.kaleidr.com/platform-api/quota-and-rate-limits"
}
429 還包含 Retry-After: 3600 header — 在此之前不要 retry。
如果您需要超過 allowance 的使用量，請 聯絡我們 — 更高 volume 會按 organization 提供，Enterprise 還可以從 獨立 CDN 提供服務。
Rate limit 與 concurrency
quota 前還有兩個 limit，兩者都會使用 429 shed 超額 request，而不是 排隊：
- Requests per minute, per key — 60 秒滑動視窗。每個 key 都有自己的 rate。
- Concurrent streams, per organization — 跨組織所有 key 的 simultaneous streaming request。
請使用 backoff 重試。此處的 429 表示「目前 request 過快」；body 中帶有
meter 的 429 表示已達到 monthly cap。
處理方式
- 將 429 視為「降低速度 / 升級」，而不是「系統損壞」。back off 後重試。
- 在 UI 中顯示 stream 中的
quotaevent（remaining budget）。 - 完整 status table 請參閱 Errors。