본문으로 건너뛰기

Quota 및 rate limit

조직당 하나의 청구​

Platform usage는 key가 아니라 organization 단위로 측정됩니다 — org가 가진 모든 key는 하나의 공유 monthly budget을 사용하고 함께 rate-limit됩니다. 하나의 key, 하나의 bill: AI, maps, design 모두 같은 org meter를 사용합니다.

budget은 monthly calendar cycle로 reset됩니다.

Plan에 포함되는 항목​

organization의 plan은 key가 접근할 수 있는 영역과 공유 monthly token budget을 모두 결정합니다:

PlanAPI surfaceMonthly API tokensMonthly map loads
FreeBasemaps만 — maps scope와 tile product를 가진 publishable keyn/a(ai scope 없음)50,000
Profull platform(ai, maps, design; browser + server keys)5,000,00050,000
Enterprisefull platform50,000,00050,000

모든 plan은 같은 map-loads allowance를 가집니다 — plan은 tokens, API surface, feature에서 차이가 납니다. allowance보다 높은 Enterprise volume은 더 높은 plan 단계가 아니라 organization별 추가량으로 제공됩니다.

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로 제공되므로 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를 기록하고 후속 대응합니다.

하지만 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 등 하나의 map load(대략 20 tile request)가 위에서 설명한 공유 monthly allowance를 사용합니다. keyed embed 외부에서 tile.kaleidr.com을 제3자가 직접 사용하면 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이 있으며, 둘 다 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를 "broken"이 아니라 "slow down / upgrade"로 처리하세요. back off 후 retry.
  • stream 중 quota event(remaining budget)를 UI에 표시하세요.
  • 전체 status table은 Errors를 참조하세요.