クォータとレート制限
組織ごとに1つの請求
Platform usage は key ごとではなく organization ごと に計測されます — org が持つすべての key が 1つの共有 monthly budget を消費し、一緒に rate-limit されます。1 key、1 bill： AI、maps、design はすべて同じ org meter から差し引かれます。
budget は monthly calendar cycle で reset されます。
Plan に含まれるもの
organization の plan は、key がアクセスできる範囲と共有 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 | full platform（ai, maps, design; browser + server keys） | 5,000,000 | 50,000 |
| Enterprise | full platform | 50,000,000 | 50,000 |
すべての plan は同じ map-loads allowance を持ちます — plan の違いは tokens、API surface、features です。allowance を超える Enterprise volume は 上位 plan ではなく org ごとの追加枠として提供されます。
Free-plan key は basemap embed を提供し、token ではなく map loads として 計測されます。AI と design surface にアクセスするには kaleidr.com/billing で upgrade してください。plan 変更は 数分以内に既存 key に適用され、re-mint は不要です — ただし Free で mint された key は 次の rotate 時に re-scope されます。
429 body
cap を超える request は 429 Too Many Requests と
flat top-level body を返します — structured 429 payload は field を
detail object で wrap しません（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 として通知されるため、stream が終了する前に
UI が反応できます。
flat 429 と wrapped 429 の完全な違いは Errors — Envelope を参照してください。
Allowance を超えた場合
allowance を超えたときの動作は plan によって異なり、2つのケースは 意図的に違います。
Free は allowance で停止します。超過する request は
429 map_load_quota_exceeded を返します。この境界が free basemap product です。
Pro と Enterprise は提供を継続します。有料 account の overage は billing の話であり outage ではないため、月途中で embed が停止することはありません — overage を記録して後から対応します。
ただし grace は無制限ではありません。有料 plan は allowance の 5倍 で
429 map_load_hard_stop により停止します。通常の embed がここまで達することはありません。
この ceiling は、page source から publishable key をコピーした第三者が
無制限の bill を発生させることを防ぐために存在します。購入した map-load pack は
allowance を増やし、ceiling もそれに比例します。
soft band に頻繁に達する場合、workaround ではなく allowance の追加が必要です — お問い合わせ。
Basemap access
designed basemaps は Kaleidr account の一部であり、
standalone public tile API ではありません。<kaleidr-map> embed と SDK は
publishable key（maps scope）で認証され、shared-map の open、published/embedded view、
SDK basemap session など1回の map load（約20 tile request）が、上記の shared monthly allowance を
消費します。keyed embed 外から tile.kaleidr.com を第三者が直接利用すると
429 と次の body で block されます：
{
"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 の前に2つの limit があり、どちらも excess を queue せず 429 で shed します：
- Requests per minute, per key — sliding 60-second window。各 key に 独自 rate があります。
- Concurrent streams, per organization — org の全 key をまたぐ simultaneous streaming request。
backoff して retry してください。ここでの 429 は「今は速すぎる」という意味です。
body に meter を含む 429 は monthly cap に達したことを意味します。
対応方法
- 429 は「slow down / upgrade」として扱い、「broken」とは扱わないでください。back off して retry。
- stream 中の
quotaevent（remaining budget）を UI に表示してください。 - 完全な status table は Errors を参照してください。