配额与速率限制
每个组织一张账单
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 超额请求，而不是 排队：
- Requests per minute, per key — 60 秒滑动窗口。每个 key 都有自己的 rate。
- Concurrent streams, per organization — 跨组织所有 key 的 simultaneous streaming request。
请使用 backoff 重试。此处的 429 表示“当前请求过快”；body 中带有
meter 的 429 表示已达到 monthly cap。
处理方式
- 将 429 视为“降低速度 / 升级”，而不是“系统损坏”。back off 后重试。
- 在 UI 中显示 stream 中的
quotaevent（remaining budget）。 - 完整 status table 请参阅 Errors。