クォータとレート制限
Kaleidr では利用を 2 つの方法で制限しており、どちらの場合も HTTP 429 が返されます。
- クォータは、1 回の請求期間中に組織が使用できる量です。使い切った場合は、期間がリセットされるまで待つか、追加分を購入する必要があります。
- レート制限は、呼び出し可能な頻度を定めます。上限に達した場合は、数秒間呼び出しのペースを落としてください。
応答本文を確認すれば、どちらの制限に該当したかを判別できます。このページでは、それぞれの応答形式、呼び出しごとの課金、対処方法を説明します。
2 種類の利用枠
使用量は組織単位で、2 つの利用枠に分けて計上されます。
| 利用枠 | 消費対象 | Free | Pro | Enterprise |
|---|---|---|---|---|
| AI クレジット | チャットの回答、場所の検索、住所検索、デザイン分析 | 1 期間あたり 500,000 | 1 期間あたり 5,000,000 | 契約に基づく個別設定 |
| マップ読み込み | Tile セッションごと、および公開・埋め込みマップの表示ごと | 1 期間あたり 50,000 | 1 期間あたり 50,000 | 基本枠は同じ。より多くの使用量は契約で設定 |
この 2 つの利用枠について、誤解されやすい点が 3 つあります。
- AI クレジットは組織全体で 1 つの利用枠を共有します。 API キーは、チームが Kaleidr のアプリ内で使うものと同じ AI クレジットを消費します。API 専用の予算はなく、すべてのキーで同じ枠を共有します。
- 期間は請求期間です。 有料サブスクリプションの場合は、契約開始日を起点とする毎月のサイクルです。サブスクリプションがない場合は暦月が適用されます。期間は米国東部時間の午前 0 時に切り替わります。
- 追加パックは上限を引き上げます。 購入した AI クレジットとマップ読み込みのパックはプランの利用枠に加算され、応答内の
limitに反映されます。
プラン変更は数分以内に既存のキーへ反映されます。キーを新しく作成する必要はありません。
各呼び出しの課金対象
| 呼び出し | 利用枠 | 課金 |
|---|---|---|
POST /chat/control/stream, /chat/summary/stream, /chat/button/stream, /spot/overview/stream | AI クレジット | 回答に使用した入力と出力のトークン数。詳しくはストリームの課金方法を参照してください。 |
POST /chat/control/route | なし | 課金されません。経路計画中はクレジットが一時確保されますが、必ず解放されます。 |
POST /spot | AI クレジット | 結果の有無を問わず、呼び出しごとの定額料金です。want に content または photos が含まれ、この呼び出しのためにコンテンツを取得した場合は /retrieval/poi/enrich と同額、それ以外で address が含まれる場合は /retrieval/geocode/forward と同額です。以前のリクエストで取得済みのコンテンツは無料です。場所、地域、境界線のみを要求する場合は無料です。 |
GET /retrieval/poi/enrich | AI クレジット | コンテンツが見つからなくても、呼び出しごとに定額料金が発生します。 |
GET /retrieval/geocode/forward | AI クレジット | 結果がなくても、呼び出しごとに少額の定額料金が発生します。ただし、検索自体が失敗した場合は課金されません。 |
POST /design/analyze | AI クレジット | 呼び出しが成功した場合に定額料金が発生します。失敗時は無料です。 |
POST /design/apply-direct, GET /design/styles, /design/samples, /design/themes | なし | 課金されません。 |
POST /sdk/sessions の chat、editor、viewer | なし | 課金されません。 |
POST /sdk/sessions の tile | マップ読み込み | セッション交換ごとに 1 回のマップ読み込みとして計上されます。 |
POST /sdk/share-sessions | なし | 課金されません。そのセッションで実行したチャット呼び出しは、マップの所有者に課金されます。 |
POST /inference-api/vendor/mapping/propose（ビジネスデータアップロード API のマッピング提案） | AI クレジット | 提案で使用したトークン数に応じて課金されます。API キーではなく、アカウントのサインイン認証で呼び出します。クレジットが尽きると 429 quota_exceeded が返ります。また、アカウントごとに 1 時間 30 回という独立した制限があり、2 種類の 429 はレスポンス本文が異なります。アップロード、公開、公開解除、削除は無料です。 |
現在の使用量と上限は kaleidr.com/billing で確認できます。
ストリームの課金方法
ストリーミング呼び出しの費用は完了するまで確定しないため、次の 2 段階で課金されます。
- 確保。 リクエストが受け付けられると、利用枠から一定数のクレジットが確保されます。必要な額を確保できない場合、回答の生成前に
quota_exceededで拒否されます。つまり、実際の費用が少ない呼び出しでも、開始時には確保分の余裕が必要です。 - 精算。 ストリームの終了時に、確保額が実際の課金額（回答に使用したトークン数）に置き換わります。実際の費用は確保額より多い場合も少ない場合もあります。
ストリームを中断した場合や、回答が完成する前に失敗した場合はトークン数が確定しないため、推定値に基づいて課金されます。
| ストリーム | 未完了で終了した場合の課金 |
|---|---|
/chat/control/stream | 送信した会話（リクエスト内の user と assistant のメッセージ）の推定量と、すでに配信したテキストの推定量（確保額まで計上）のうち、大きい方です。確保額を超える可能性があります。 |
/chat/summary/stream, /chat/button/stream, /spot/overview/stream | すでに配信したテキストの推定量です。確保額を超えることはありません。 |
したがって、チャットストリームを早期に閉じても、長い会話が無料になるわけではありません。回答をほとんど読み取らなくても、少なくとも送信したリクエストのサイズに応じた課金が発生します。次の回答に必要な履歴だけを送信し、リクエストを小さくしてください。ストリームの読み取りを参照してください。
ストリームの実行中に上限に達しても、そのストリームは中断されません。上限の確認は受付時に行われ、次のリクエストが拒否されます。
拒否されたリクエストは課金されません。 レート制限、同時実行数の上限、検証エラー、本文サイズ超過などによって処理前に拒否されたリクエ ストは、AI クレジットも同時実行枠も保持しません。拒否分の料金を支払うことなく再試行できます。
キー単位の上限
キーには月間上限（monthly_cap_tokens、キー管理 API で設定）を指定できます。1 期間中にそのキーが組織の AI クレジットから消費できる額を制限します。組織全体の利用枠が最終的な上限であることは変わりません。
上限が設定されたキーでリクエストによって上限を超える場合は、同じ quota_exceeded 本文で拒否されます。ただし limit と used には、組織全体ではなくそのキーの数値が入ります。
クォータ超過
HTTP/1.1 429 Too Many Requests
Retry-After: 1296000
Content-Type: application/json
{
"error": "quota_exceeded",
"detail": "Usage limit reached. Please try again later.",
"product": "b2b",
"meter": "b2b.tokens",
"tier": "pro",
"limit": 5000000,
"used": 4999100,
"remaining": 900,
"reset_at": "2026-11-01T04:00:00+00:00",
"period": "month",
"reset_in_seconds": 1296000
}
| フィールド | 意味 |
|---|---|
error | この場合は常に quota_exceeded です。このフィールドを使って処理を分岐してください。 |
detail | 人が読むための説明文です。プログラムで解析しないでください。 |
product, meter | API の AI クレジット計数器を示します。プラットフォームキーでは常に b2b と b2b.tokens です。 |
tier | 組織の契約プラン。 |
limit, used, remaining | クレジットプールの数値で す。キーごとの上限によって呼び出しが拒否された場合は、そのキーの数値になります。remaining がゼロより大きい場合もあります。必要な仮予約分を確保できなかったため、呼び出しが拒否されたという意味です。 |
reset_at | 期間の終了日時をタイムゾーンのオフセット付き ISO 8601 タイムスタンプで示します。サービスの再開時期をユーザーに伝える際は、この値を使用してください。 |
period | month。 |
reset_in_seconds | reset_at までの秒数です。これはクレジットプールがリセットされる期間の終了時刻を表します（サブスクリプションの請求サイクル、契約がない場合は暦月）。Retry-After ヘッダーにも同じ数値が設定されます。 |
レスポンス本文はフラットな構造であり、各フィールドは detail オブジェクトの中ではなく最上位にあります。
セッショントークンの場合
上記の本文はサーバーキーまたは従来のキーに返されます。セッショントークンで実行するリクエストは訪問者のブラウザー内で動作するため、拒否レスポンスから組織のプラン、使用量、上限が漏れることはありません。公開可能キーから交換したセッションと、公開マップの訪問者セッションの両方に適用されます。
{
"error": "quota_exceeded",
"detail": "Usage limit reached. Please try again later.",
"meter": "b2b.tokens",
"reset_at": "2026-11-01T04:00:00+00:00",
"reset_in_seconds": 1296000
}
| フィールド | サーバーキーまたは従来のキー | セッショントークン |
|---|---|---|
error, detail | あり | あり |
meter | あり | あり |
reset_at, reset_in_seconds | あり | あり |
product, period | あり | なし |
tier | あり | なし |
limit, used, remaining | あり | なし |
ステータス、Retry-After ヘッダー、意味は同じです。ブラウザーのコードでは error を確認し、reset_at を表示してください。limit、used、remaining は参照しないでください。使用量を表示する場合は、バックエンドのサーバーキーか kaleidr.com/billing から確認してください。
組織が利用していたはずなのに本文に used: 0 と表示された場合、API が使用量を読み取れず、安全のため呼び出しを拒否した可能性があります。reset_at まで待たず、数秒後に再試行してください。
レート制限と同時実行数
すべての実行時呼び出しの前に 3 種類の上限を確認します。超過した呼び出しは直ちに拒否され、キューには入りません。
| 制限 | 集計単位 | 対象 |
|---|---|---|
| 1 分あたりのリクエスト数 | キー | キーを使ったすべての実行時呼び出しおよびそのキーから交換したすべてのセッションによる呼び出しを、移動する 60 秒間の枠で集計します。1 つの公開可能キーを使うサイトでは、全訪問者で上限を共有します。 |
| 1 分あたりのセッション交換数 | キー | POST /sdk/sessions の呼び出しです。独立した上限なので、埋め込みのマウントは実行時呼び出し数を消費しません。 |
| 同時リクエスト数 | 組織 | 組織のすべてのキーを通じて同時に進行中の呼び出しです。ストリームは開いている間ずっと数えられます。 |
キーの 1 分あたりのリクエスト上限は、API キーページやキー管理 API から変更できません。さらに高いレートが必要な場合はお問い合わせください。
これらの拒否レスポンスは、すべて同じ本文形式とヘッダーを使用します。
HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json
{ "error": "rate_limited", "detail": "API key rate limit exceeded. Slow down." }
error | 意味 | 対処方法 |
|---|---|---|
rate_limited | キー の 1 分あたりのリクエスト数、またはセッション交換の上限に達しました。 | Retry-After で指定された秒数を待ち、ランダムな揺らぎを加えて再試行します。 |
org_overloaded | 組織内で進行中の呼び出しが多すぎます。 | 進行中の呼び出しが終了するまで待って再試行します。不要なストリームは閉じます。 |
b2b_overloaded | API 全体の処理能力が上限に達しました。 | Retry-After の秒数だけ待ち、バックオフを使って再試行します。 |
limiter_unavailable | レート制限システムが応答できませんでした。 | しばらくしてから再試行します。利用者の呼び出しレートが原因ではないため、ペースを落としても解決しません。 |
visitor_limit_reached | 公開マップのチャットで、ある訪問者が 1 分または 1 日の上限を超えました。 | 訪問者に後で再試行するよう案内します。公開マップでのチャットを参照してください。 |
ネットワークのエッジでも、IP アドレスと認証情報ごとにレート制限が適用されます。そこでブロックされたリクエストには、本ページ記載の JSON 本文は返されません。Kaleidr 形式の本文がない 4xx レスポンスは、ペースを落として後で再試行するように扱ってください。
マップ読み込み
訪問者向けに Kaleidr マップが起動するたびに、マッ プ読み込みが 1 回計上されます。
product: "tile"のセッション交換ごと。SDK による更新と要素の再マウントも含まれます。- 公開または埋め込みマップの表示ごと。
埋め込み Editor のセッション交換はマップ読み込みに含まれません。代わりに、公開可能キーを使用したベースマップへのリクエスト（スタイル、スプライト、フォント）がまとめて計上されます。組織が 1 時間以内にこれらを 20 回送信するごとに、後からマップ読み込みが 1 回加算されます。上限に達していてもこれらのリクエストは拒否されません。マップタイルデータ自体は計上されません。
すべてのプランで割り当て上限に達すると停止します。 利用枠を使い切ると、次の読み込みは拒否され、回数にも加算されません。有料プランにも猶予枠はありません。マップ読み込みパックを購入すると、上限が直ちに引き上げられます。
セッション交換で拒否された場合のレスポンスは次のとおりです。
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{ "detail": "map_load_quota_exceeded" }
この本文は上記のフラットなクォータ本文とは異なり、detail に格納されます。また Retry-After ヘッダーはありません。期間が更新されるかパックを追加するまで、再試行しても解決しません。ページでは Tile 埋め込みが起動せず、SDK は kaleidr session exchange failed (429) をログに出力します。
タイルへの直接リクエスト
ベースマップのタイルホストは公開タイル API ではありません。Kaleidr のベースマップを表示するための対応方法は Tile 製品を使用することです。tile.kaleidr.com に対して、許可されたオリジンで有効な公開可能キーを用いる Kaleidr 埋め込みから送られていないリクエストは拒否されます。
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Cache-Control: no-store
Content-Type: application/json
{
"error": "tile_access_restricted",
"message": "Direct access to tile.kaleidr.com requires a Kaleidr publishable key. Mint a free one at kaleidr.com/api-keys and pass it as ?key= from an allowed origin. Kaleidr-hosted maps and embeds are unaffected.",
"docs": "https://docs.kaleidr.com/get-an-api-key"
}
このレスポンスはプラットフォーム API ではなくタイルホストから返るため、API の detail ではなく message が使われます。新規作成または編集したキーがタイルで有効になるまで、数分かかることがあります。
ストリームの quota イベント
チャットストリームは課金が完了した後に利用枠の状態を通知します。quota イベントはストリームの最後のイベントで、end または error の後に送信されます。
event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}
これはサーバーキーまたは従来のキーで読み取ったストリームのイベントです。セッショントークン（公開可能キーや公開マップの訪問者セッションから取得）で読み取る場合、イベントにプランや使用量の数値は含まれません。
event: quota
data: {"type": "quota", "meter": "b2b.tokens", "reset_at": "2026-11-01T04:00:00+00:00"}
| フィールド | サーバーキーまたは従来のキー | セッショントークン |
|---|---|---|
type, meter, reset_at | あり | あり |
product, period | あり | なし |
tier | あり | なし |
used, limit | あり | なし |
サーバーキーを利用する場合、二度目のリクエストをせずに、 このイベントで使用量メーターを更新できます。ただし、次の 3 つの制約があります。
remainingフィールドはありません。limit - usedを計算してください。- このイベントはベストエフォートで送信されます。届かないままストリームが終了する場合もあるため、待ち続けないでください。
- これは実績の通知であり、事前の警告ではありません。回答の途中には届かず、ストリームを停止することもできません。
受信するにはレスポンス本文が閉じるまで読み取り続けてください。end で読み取りを止めるクライアントはこのイベントを見逃します。
コードで 429 を処理する
判断する前にレスポンス本文を読んでください。ステータスだけでは再試行すべきか分かりません。
| 受信内容 | 再試行 | タイミング |
|---|---|---|
error: "quota_exceeded" | いいえ | reset_at の後、またはクレジットを追加するかキーの上限を引き上げた後です。ユーザーに上限到達を伝えます。 |
error: "rate_limited", "org_overloaded", "b2b_overloaded", "limiter_unavailable" | はい | Retry-After 秒の経過後、ランダムな揺らぎを加え、多くても数回だけ再試行します。 |
error: "visitor_limit_reached" | いいえ | 後で再試行するよう訪問者に案内します。 |
detail: "map_load_quota_exceeded" | いいえ | 期間が更新されるか、マップ読み込みパックを追加した後です。 |
error: "tile_access_restricted" | いいえ | 埋め込みを修正し、許可されたオリジンで公開可能キーを付けて Tile 製品を使用します。 |
const RETRYABLE = new Set(['rate_limited', 'org_overloaded', 'b2b_overloaded', 'limiter_unavailable']);
async function callKaleidr(url, init, attempt = 0) {
const res = await fetch(url, init);
if (res.status !== 429) return res;
const body = await res.json().catch(() => ({}));
if (RETRYABLE.has(body.error) && attempt < 3) {
const seconds = Number(res.headers.get('retry-after')) || 5;
await new Promise((resolve) => setTimeout(resolve, (seconds + Math.random()) * 1000));
return callKaleidr(url, init, attempt + 1);
}
const error = new Error(body.error || body.detail || 'rate limited');
error.status = 429;
error.code = body.error || body.detail;
error.resetAt = body.reset_at; // present for quota_exceeded
throw error;
}
ブラウザー内の JavaScript では、プラットフォーム API のレスポンスから Retry-After ヘッダーを読み取れます。
関連ペ ージ
- エラー：すべてのステータスとコード。
- SSE ワイヤー仕様：ストリームでの
quotaイベントの位置。 - ストリームの読み取り：再試行とタイムアウト処理を備えた完全なクライアント。
- API キーの取得：各プランの内容。