エラー
これは Kaleidr プラットフォーム API が返すエラーの完全な一覧です。各エラーには HTTP ステータスと、処理を分岐する際に使用できる短く安定した文字列であるコードがあります。ステータスだけでは原因を判断できません。403 には複数の原因があり、429 は「リクエスト頻度を下げる必要がある」場合と「クォータを使い切った」場合の両方を表します。
コードが常に同じフィールドにあるとは限らないため、まずレスポンス形式を確認します。
レスポンス形式
| 形式 | 例 | 用途 |
|---|---|---|
| ラップされたコード | {"detail": "origin_not_allowed"} | 401、403、404、413、500、503 のほぼすべて、422 のリクエスト制限コード、および 2 種類の 429（map_load_quota_exceeded とアップロード API の ingest_rate_limited）。コードは detail の文字列です。 |
| フラットなオブジェクト | {"error": "rate_limited", "detail": "API key rate limit exceeded. Slow down."} | その他すべての 429。コードは error、detail はユーザー向けの説明文です。クォータエラーには追加のフィールドがあります。 |
| 検証エラーのリスト | {"detail": [{"loc": ["body", "product"], "msg": "…", "type": "…"}]} | リクエスト本文やクエリの形式が不正な場合の 422。detail は問題ごとに要素を持つ配列です。 |
| 200 で返されるエラー | {"error": "Route planning failed."} | POST /chat/control/route のみ。後述を参照してください。 |
いずれの形式からもコードを読み取る関数：
async function kaleidrError(res) {
const body = await res.json().catch(() => ({}));
const code =
typeof body.error === 'string' ? body.error : // flat 429
typeof body.detail === 'string' ? body.detail : // wrapped code
Array.isArray(body.detail) ? 'validation_error' : // 422
'unknown_error';
return { status: res.status, code, body, retryAfter: Number(res.headers.get('retry-after')) || null };
}
重要なヘッダーは 2 つあります。429 レスポンスの Retry-After は秒単位の待機時間を表し、X-Request-Id がある場合はサポートに問い合わせる際にリクエストを特定できます。
認証: 401
API が認証情報を受け付けません。
| コード | 発生条件 | 対処方法 |
|---|---|---|
Invalid or missing API key | 認証情報が送信されていない、またはキーが不明・失効・期限切れです。ほかにも、期限切れのセッショントークン、キーが失効または猶予期間なしでローテーションされたセッション、キーからオリジンや製品が削除されたセッション、プランのダウングレード前に発行されたセッション、停止中またはプランのない組織が該当します。 | kaleidr.com/api-keys でキーと状態を確認します。セッションの場合は交換し直します。有効なキーでも失敗が続く場合は少し待って再試行してください。一時的なプラットフォーム障害でも同じ応答が返ることがあります。 |
publishable_requires_session | 公開可能キー（kld_pk_…）がランタイムエンドポイントに送信されました。 | ブラウザーでは SDK に交換させるか、最初に POST /sdk/sessions を呼び出します。バックエンドではサーバーキーを使用します。 |
認可: 403
API は認証情報を認識しましたが、このリクエストを拒否しています。
| コード | 発生条件 | 対処方法 |
|---|---|---|
insufficient_scope | このエンドポイントまたは製品に必要なスコープを持たずにキーが作成されました。 | 必要なスコープを持つキーを使用します。既存のキーにスコープを追加することはできません。 |
tier_capability_not_allowed | キーは該当するスコープまたは製品を持っていますが、組織の現在のプランには含まれていません。公開マップの所有者のプランにチャットが含まれない場合にも返されます。ただし vendor は例外です。Enterprise 未満のプランで vendor を持つキーは拒否されず、回答が自社データを使用しなくなります。 | プランを変更するか、プランに含まれる製品 を使用します。 |
server_key_in_browser | サーバーキー（kld_sk_…）が Origin ヘッダーとともに送信されました。 | バックエンドから呼び出してください。キーがページのソースに含まれていた場合はローテーションします。 |
session_origin_mismatch | セッショントークンが発行元と異なるオリジンで使用されたか、公開マップのセッションが Origin なしで使用されました。 | 使用するページでセッションを交換してください。 |
ip_not_allowed | IP 許可リストを持つサーバーキーまたは旧形式のキーが許可リスト外のアドレスから呼び出されたか、呼び出し元アドレスを特定できませんでした。 | 許可済みアドレスから呼び出すか、キーの allowed_ips を変更します。 |
publishable_key_required | サーバーキーまたは旧形式のキーで POST /sdk/sessions を呼び出しました。 | 交換時には公開可能キーを使用します。 |
origin_required | セッション交換に Origin ヘッダーがありません。 | ブラウザーのページから交換します。 |
origin_not_allowed | ページのオリジンがキーの許可済みオリジンや公開マップの許可済みドメインにありません。 | 完全一致するオリジンをキーに、またはドメインをマップに追加します。 |
product_not_allowed | キーが特定の製品に制限され、別の製品へのリクエストが行われました。セッション交換では、要求した product が公開可能キーの許可製品に含まれません。ランタイムでは、サーバーキーまたは旧形式のキーが許可外の製品のエンドポイントを呼び出しました。例として、tile に制限されたキーで /chat/* を呼ぶ場合があります。 | allowed_products を変更するか、別のキーを使用します。 |
chat_disabled | 公開マップの交換：マップの Kaleidr AI が、要求された機能をオンにしていません。 | Studio でマップの Kaleidr AI タイルの Control Tower または Popup Window をオンにします。 |
feature_not_granted | ポップアップ Chat 用に開いた公開マップのセッションが /chat/control/stream で使用されました。機能ごとに別のセッションがあります。 | "feature": "control_tower" でセッションを交換します。Control Tower がオンの間、マップがこれを付与します。 |
owner_has_no_organization | 公開マップの交換：マップ所有者に課金先の組織がありません。 | 所有者は組織を作成するか、既存の組織に参加する必要があります。 |
見つかりません: 404
| コード | 発生条件 | 対処方法 |
|---|---|---|
not_found | 公開マップの交換：指定の share_id を持つ公開マップも共有リンクもありません。 | ID とマップの公開状態を確認します。 |
sessions_disabled | プラットフォームでセッション交換が無効 です。 | 利用者側では変更できません。サポートに連絡してください。 |
Not Found | パスが存在しません。 | /inference-api/b2b/v1 プレフィックスも含め、エンドポイントの URL と照合してください。 |
検証: 422
リクエスト本文またはクエリ文字列がエンドポイントの受け付ける形式と一致しません。detail は配列で、各要素の loc がフィールド名、msg が問題の内容を示します。
{
"detail": [
{ "type": "missing", "loc": ["body", "product"], "msg": "Field required", "input": {} }
]
}
リクエストを修正し、同じ内容をそのまま再送しない でください。ストリーミングエンドポイントの /chat/summary/stream と /chat/button/stream は、本文の形式が不正な場合、フィールド長超過を除いて 422 ではなく 500 を返します（下記参照）。
リクエスト制限: コード付き 422
形式は正しいもののサイズ制限を超えるリクエストも 422 になります。この場合はラップされた形式で、detail は配列ではなくコード文字列です。課金は発生しません。
{ "detail": "conversation_too_long" }
| コード | エンドポイント | 発生条件 | 対処方法 |
|---|---|---|---|
too_many_messages | /chat/control/stream | messages が 400 件を超えています。 | 直近の会話ターンだけ を送信します。 |
message_too_long | /chat/control/stream | 1 件のメッセージの content が 64,000 文字を超えています。 | メッセージを短くします。 |
conversation_too_long | /chat/control/stream | 全メッセージの content の合計が 200,000 文字を超えています。 | 古いターンを削除して再送します。 |
invalid_session_id | /chat/control/stream | session_id が 128 文字を超えるか、英数字、_、.、:、- 以外の文字を含んでいます。 | UUID など、その形式の ID を使用します。 |
lang_too_long | /chat/control/stream | lang が 35 文字を超えています。 | pt-BR のような BCP 47 言語タグを送ります。 |
invalid_layout | /chat/control/stream | layout が 16 文字を超えています。 | viewer がガイドのレイアウトを表示している間は guide を送るか、省略します。 |
field_too_long | /chat/summary/stream, /chat/button/stream | テキストフィールドが長さの上限を超えたか、リストの要素数が上限を超えています。 | フィールドを短くします。上限はエンドポイントに記載されています。 |
チャットストリームの制限はエンドポイントを参照してください。
リクエストが 大きすぎます: 413
| コード | 発生条件 | 対処方法 |
|---|---|---|
request_too_large | 本文が 2 MiB、または /design/* エンドポイントで 5 MiB を超えています。レスポンス本文は {"detail": "request_too_large"} です。課金は発生しません。 | 会話履歴や設計リクエストのサンプル行を減らしてください。同じ本文を再送しないでください。 |
request_body_too_large | /shared-api 以下のキー管理またはビジネスデータのリクエストが 1 MiB、またはアップロード呼び出し POST /shared-api/datahub/ingests が 32 MiB を超えています。 | 本文を小さくします。アップロードについてはビジネスデータのアップロードを参照してください。 |
どのエンドポイントの上限も大幅に超えるサイズを宣言したリクエストは、API に到達する前にネットワークエッジで拒否される場合があります。この応答には Kaleidr の JSON 本文がなく、読み取れるコードもありません。送信量を減らしてください。
サイズ超過など処理前に拒否されたリクエストは課金されず、その後に AI クレジットや同時実行スロットを占有することもありません。
クォータとレート制限: 429
再試行を判断する前にレスポンス本文を確認してください。
| コード | フィールド | Retry-After | 発生条件 | 対応方法 |
|---|---|---|---|---|
quota_exceeded | error | reset_at までの秒数 | 組織の AI クレジットが呼び出しに必要な量に満たないか、そのキー固有の月間上限を超える場合です。アップロード API のマッピング提案呼び出しでも返されます。 | 再試行しないでください。reset_at まで待つか、クレジットを追加するか、キーの上限を引き上げてください。 |
rate_limited | error | 5 | キーの 1 分あたりのリクエスト数の上限に達した場合です。キー、公開済みの地図、または単一のアドレスに対するセッション交換が多すぎる場合も該当します。 | Retry-After に指定された秒数待ち、ランダムな待機時間を加えて再試行してください。 |
org_overloaded | error | 5 | 組織内で同時に実行中の呼び出しが多すぎます。 | 実行中の呼び出しが終了してから再試行してください。不要になったストリームは閉じてください。 |
b2b_overloaded | error | 5 | すべての呼び出し元に対して API の処理能力が上限に達しています。 | Retry-After に指定された秒数待ち、再試行の間隔を段階的に延ばしながら再試行してください。 |
limiter_unavailable | error | 5 | レートリミッターが応答できませんでした。 | 少し時間を置いて再試行してください。リクエスト頻度が原因ではありません。 |
visitor_limit_reached | error | 5 | 公開済みの地図のチャットで、ある訪問者が 1 分または 1 日あたりの利用上限を超えました。 | 訪問者に、後ほど再試行するよう案内してください。 |
map_load_quota_exceeded | detail | なし | tile に対する POST /sdk/sessions で、組織の地図読み込み枠を使い切りました。 | 再試行しないでください。期間がリセットされるまで待つか、地図読み込みパックを追加してください。 |
quota_exceeded のレスポンス本文には次の数値が含まれます：
{
"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": "Usage limit reached. Please try again later.",
"meter": "b2b.tokens",
"reset_at": "2026-11-01T04:00:00+00:00",
"reset_in_seconds": 1296000
}
各フィールド、キー単位の上限の形式、処理コード例についてはクォータとレート制限を参照してください。
サーバーエラー: 5xx
| ステータス | コード | 発生条件 | 対処方法 |
|---|---|---|---|
| 500 | An internal error occurred. Please try again. | 予期しない障害です。 | 少し待って 1 回再試行してください。 |
| 500 | map_design_analyze_failed | POST /design/analyze でテーブルの分析に失敗しました。課金はありません。 | 列とサンプル行を確認して再試行します。 |
| 500 | Summary stream error | POST /chat/summary/stream を開始できませんでした。本文が読めないか、建物リクエストに address がありません。長すぎるフィールドの場合は代わりに 422 field_too_long になります。 | 本文を修正します。 |
| 500 | Button chat stream error | POST /chat/button/stream を開始できませんでした。本文が読めないか、query がありません。長すぎるフィールドの場合は代わりに 422 field_too_long になります。 | 本文を修正します。 |
| 503 | sessions_not_configured | プラットフォーム障害でセッション交換を利用できません。 | 再試行し、解消しなければサポートに連絡します。 |
| 503 | share_grant_unavailable | 公開マップの交換：マップ設定を読み取れませんでした。 | 少し待って再試行します。 |
ステータス 200 でのエラー
ルートを作成できない場合でも、POST /chat/control/route は 200 を返します：
{ "error": "Route planning failed." }
レスポンスには error があり、action はありません。ステータスだけを確認するクライアントは成功と誤認し、その後 action を読もうとして失敗します。必ず本文の error を確認してください。文言はユーザーに表示できるよう作られています。詳細：経路案内。
GET /retrieval/geocode/forward にも類似した動作があります。内部検索が失敗すると results が空の 200 を返し、これは一致結果がなかった場合と同じです。
ストリームでのエラー
ここまでの説明はストリーム開始前に適用されます。拒否されたストリーミングリクエストは通常の HTTP エラーです。レスポンスが 200 になり、フレー ムの配信が始まると、失敗は error イベントで通知されます：
event: error
data: {"type": "error", "code": "upstream_stall", "message": "The AI service stopped responding. Please try again.", "partial_text": "The Louvre sits"}
| ストリーム | code | 発生条件 | 対処方法 |
|---|---|---|---|
/chat/control/stream | upstream_stall | 回答生成が進まなくなったか、ストリームが最大約 10 分の長さに達しました。 | 再試行を提示します。有用なら partial_text を残します。 |
/chat/control/stream | なし | 回答中のその他のエラーです。 | message を表示します。再試行で成功する場合があります。 |
/chat/summary/stream | なし | 要約が失敗しました。 | message を表示するか、要約なしで続行します。 |
/spot/overview/stream | なし | 概要が失敗したか、ref を説明できません。説明できない場合はイベントに ref が含まれます。対象地点にない poi: または region: の参照、hint.name のない place:、API が説明を提供しない建物または住所です。 | 概要を表示しません。ref を含むイベントは再試行しないでください。 |
/chat/button/stream | なし | このストリームには error イベントがありません。失敗すると end なしで接続が切れます。 | end なしで閉じたストリームは失敗として扱います。 |
すべてのストリームに共通するルール：
errorイベントはendの代わりに送られます。その後に届くのは省略可能なquotaイベントだけです。endとerrorのどちらもないまま接続が切れた場合は失敗です。quotaはエラーではありません。endまたはerrorの後に送信される利用量レポートです。セッショントークンによるストリームではtype、meter、reset_atのみを含みます。- 未知のイベント名はエラーではありません。無視してください。
ストリームが途中で失敗・中断しても課金対象です。/chat/control/stream の料金は送信した会話の推定量より小さくならないため、開始時の予約量を超えることがあります。ストリームの課金方法を参照してください。再試行は別のリクエストとして新たに課金されます。
ブラウザーにより隠されるエラー
オリジンや認証情報が拒否されたレスポンスには CORS ヘッダーがなく、ブラウザーがステータスと本文をコードから隠します。ページのコンソールには CORS エラーが表示され、fetch は拒否されます。SDK は [kaleidr:<product>] を含むエラーを記録します。
実際のコードを確認するには、Network タブで失敗したリクエストを選択してください。よくあるものは origin_not_allowed、Invalid or missing API key、server_key_in_browser です。CORS と許可オリジンを参照してください。
Kaleidr の JSON 本文を伴わない 4xx は API より手前のネットワークエッジで返されたものです。原因はレート制限（頻度を下げて後で再試行）か、宣言されたリクエストサイズがすべてのエンドポイント上限を大幅に超えていることです（送信量を減らす。同じリクエストの再試行では同じ結果になります）。
タイルホスト
有効な公開可能キーと許可されたオリジンを持つ Kaleidr の埋め込みコンポーネント以外から tile.kaleidr.com にアクセスすると、次が返されます：
| ステータス | コード | Retry-After | 対処方法 |
|---|---|---|---|
| 429 | tile_access_restricted（error に格納され、message と docs を伴う） | 3600 | 公開可能キーを使って Tile 製品を利用し、キーにオリジン許可リストがある場合はページのオリジンを追加してください。 |
キー管理
https://api.kaleidr.com/shared-api/api-keys のエラーです。API Keys ページで使用され、アカウントのアクセストークンを使って直接呼び出すこともできます。すべてラップされた形式です。
| ステータス | コード | 発生条件 | 対処方法 |
|---|---|---|---|
| 401 | さまざま | 有効なアカウントアクセストークンがありません。ここではプラットフォームキーを受け付けません。 | 再ログインします。 |
| 403 | org_admin_required | アカウントが組織の所有者でも管理者でもありません。 | 所有者または管理者に依頼してください。 |
| 403 | plan_required | 組織にプランがありません。 | kaleidr.com/billing でプランを選択します。 |
| 403 | free_plan_publishable_only | Free プランでサーバーキーが要求されました。Free でサーバーキーまたは旧形式キーをローテーションした場合にも返されます。 | 公開可能キーを作成するか Pro に移行します。 |
| 403 | tier_capability_not_allowed | キー作成時：scopes または allowed_products がプランの許可しない内容を指定しています。実際には Free または Pro での vendor 要求が該当し、vendor_acknowledged の有無にかかわらず拒否され、キーは作成されません。キー編集時：allowed_products にプラン外の製品が含まれるか、Free で空のリストに設定されています。 | vendor には Enterprise が必要です。それ以外はプランで許可されるスコープと製品を指定します。 |
| 404 | key_not_found | 組織内にその ID のキーがありません。編集と失効はどの状態のキーにも一致するため、失効済みキーを再度失効させても 200 です。ローテーションには有効なキーが必要で、失効済みキーではこのコードを返します。 | ID を確認します。ローテーション時はキーが失効している可能性があります。 |
| 409 | key_limit_reached | 組織がプランのアクティブキー数の上限（Free 2、Pro 10、Enterprise 25）に達しています。 | キーを失効させるか、新規作成の代わりに既存キーをローテーションします。 |
| 409 | key_already_rotated | キーは既にローテーションされており、猶予期間の終了前後を問わず再度ローテーションできません。expires_at を消去したり猶予期間終了後に設定する編集も拒否されます。それ以前の expires_at やほかのフィールドは編集できます。 | 交換後のキーを使用します。 |
| 409 | key_expired | ローテーションされていないキーが期限切れになり、編集に expires_at が含まれています。期限切れキーの期限延長 はできませんが、他のフィールドは編集できます。 | 新しいキーを作成します。 |
| 413 | request_body_too_large | 本文が 1 MiB を超えています。 | 本文を小さくします。 |
| 422 | unknown_scope | scopes に ai、maps、design、vendor 以外の値があります。 | リストを修正します。 |
| 422 | unknown_product | allowed_products に chat、editor、viewer、tile 以外の値があります。 | リストを修正します。 |
| 422 | vendor_scope_requires_acknowledgement | Enterprise で vendor を持つ公開可能キーを vendor_acknowledged: true なしで要求しました。Free と Pro で同じ要求をすると 403 tier_capability_not_allowed になります。 | vendor スコープを読んでからフィールドを送ります。 |
| 422 | no_fields_to_update | 編集可能なフィールドのない編集リクエストです。 | 1 つ以上のフィールドを送ります。 |
| 422 | 検証リスト | オリジン、IP エントリ、過去の有効期限、名前の形式が不正です。 | loc のフィールドを修正します。 |
| 500 | insert_failed, session_unavailable | プラットフォーム障害です。 | 再試行します。 |
| 503 | api_key_pepper_not_configured | プラットフォーム障害でキー作成が利用できません。 | 再試行し、解消しなければサポートに連絡します。 |
ビジネスデータのアップロード
https://api.kaleidr.com/shared-api/datahub 以下のアップロードルートとマッピング提案呼び出しのエラーです。422 の原因となるファイル・フィールドの上限を含む完全な一覧はビジネスデータのアップロードにあります。ここではファイルの読み取り前に拒否されるリクエストと、リリースの公開取り消し・削除のエラーを示します：
| ステータス | コード | 発生条件 | 対処方法 |
|---|---|---|---|
| 403 | org_admin_required | アカウントが組織の所有者でも管理者でもありません。マッピング提案呼び出しでも返されます。 | 所有者または管理者に依頼します。 |
| 403 | vendor_data_not_on_plan | 組織のプランがビジネスデータのアップロードを許可していません。この機能は Enterprise 専用です。アップロード、公開、再処理、マッピング提案で返され、読み取り・公開取り消し・削除では返されません。 | Enterprise に移行します。GET /shared-api/datahub/limits はどのプランでも拒否せずに、組織がアップロード可能かどうかを返します。Free または Pro では Kaleidr Studio のマップにデータを追加できます。マップ上のデータセットを参照してください。 |
| 404 | release_not_found | 公開取り消しまたは削除の際、組織にその ID のリリースがありません。削除完了済みのリリースも含みます。 | 削除の場合は既に完了したものとして扱います。 |
| 409 | org_ingest_in_progress | 組織の別のアップロードが処理中です。アップロード、公開、再処理で返されます。 | 完了を待って再送します。 |
| 409 | release_not_published | 下書きまたは失敗したリリースの公開取り消しが呼び出されました。 | 取り消す公開はありません。代わりに削除します。 |
| 409 | release_is_published | 公開中のリリースを削除しようとしました。 | 先に公開を取り消してから削除します。 |
| 413 | request_body_too_large | アップロードリクエストが 32 MiB を超えています。 | 小さいファイルを送ります。ファイル自体には組織のサイズ上限が適用されます。 |
| 422 | detail の { "errors": [ … ] } | ファイルが行数またはサイズ制限を超える、JSON バンドルのフィールド長が超過する、JSON の入れ子が深すぎる場合です。契約で指定された上限に関する理由には上限値とプランが記されます。 | 各理由を読み、ファイルを修正します。 |
| 429 | ingest_rate_limited | 組織が過去 1 時間に 30 回アップロードを開始しました。 | 待ってから再送します。 |
| 429 | detail 内の文章 | アカウントが過去 1 時間に 30 回マッピング提案を行いました。本文に error フィールドはありません。 | 待ってから再送します。 |
| 429 | error 内の quota_exceeded | マッピング提案：組織の AI クレジットが尽きました。本文は標準のクォータレスポンスです。 | reset_at まで待つか、クレジットを追加するか、手動でマッピングを作成します。 |
Kaleidr Studio へのデータセットのアップロード
この節はキーで認証するプラットフォーム API の一部ではありません。ログイン済みのユーザーが Kaleidr Studio の Data パネルからマップにデータセットを追加し、そのサイズによってアップロードが拒否された際に Studio が受け取る内容を説明します。API キーは使用しません。意味が異なる 2 種類の拒否があります：
| ステータス | コード | 発生条件 | 対処方法 |
|---|---|---|---|
| 402 | quota_exceeded | 新しいデータセットのアップロードが、組織のプラン制限のいずれかを超えています。1 データセット内の行数、1 ファイルのサイズ、または組織内の全データセットの総行数です。limit_key が原因の制限を示します。保存済みデータは保持されます。Studio はアップグレードリンクとともにメッセージを表示します。 | より小さいファイルをアップロードするか、不要なデータセットを削除し ます。Free なら Pro に移行します。Pro または Enterprise では組織全体の合計上限引き上げについて Kaleidr に問い合わせてください。1 データセットあたりの行数とファイルサイズは次の行にある絶対上限を超えられません。 |
| 400 | VALIDATION_ERROR | すべてのプランに共通する絶対上限を超えています。64 MiB を超えるファイル、100,000 行を超えるデータセット、50,000 フィーチャーを超える地理ファイル、16 MiB を超える画像オーバーレイです。コードは error にあります。プランを変更してもアップロードは許可されません。 | ファイルをより小さく分割します。同じファイルを再送せず、アップグレードも案内しないでください。 |
どちらになるかはプランだけでなくサイズによって決まります。最初に絶対上限が確認されるため、64 MiB を超えるファイルや 100,000 行を超えるデータセットは、Free、Pro、Enterprise のどれでも 400 になります。402 は絶対上限以内でも組織のプラン上限を超えた場合で、例えばファイル上限が 32 MiB の Free で 40 MiB のファイルを送るケースです。
402 quota_exceeded
本文は問題詳細オブジェクトであり、Studio 固有の error と message も含みます。コードは error と code の両方に、文章は message と detail の両方にあります：
{
"error": "quota_exceeded",
"message": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
"type": "https://errors.kaleidr.com/datasets/quota_exceeded",
"title": "Quota Exceeded",
"status": 402,
"detail": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
"code": "quota_exceeded",
"limit_key": "studio.data.rows.max",
"limit": 250000,
"used": 248500,
"tier": "free",
"upgrade_url": "https://kaleidr.com/pricing"
}
| フィールド | 意味 |
|---|---|
error, code | 常に quota_exceeded。同じ値が 2 回現れます。 |
message, detail | 同じ文章が 2 回現れます。上限を平易に説明し、ユーザー表示用に作られています。 |
type | 常に https://errors.kaleidr.com/datasets/quota_exceeded。 |
title | 常に Quota Exceeded。 |
status | 常に 402。 |
limit_key | アップロードを拒否した制限。次の表を参照してください。 |
limit | その単位で表した組織の上限。 |
used | 合計上限では組織が既に保持している行数。ほかの 2 種類ではこのアップロードの行数または MiB です。 |
tier | 組織のプラン：free、pro、enterprise。プランを読めない場合は unknown となり、Free の上限が適用されます。 |
upgrade_url | プラン変更先の URL。 |
limit_key | 制限 | limit と used の単位 | 文章 |
|---|---|---|---|
studio.dataset.rows.max | 1 データセットの行数 | 行 | 「このプランでは 1 データセットにつき 50,000 行まで利用できます。小さいファイルをアップロードするか、プランを変更してください。」 |
studio.dataset.file.mb | アップロードする 1 ファイルのサイズ | MiB | 「このプランでは最大 32 MB のファイルを利用できます。小さいファイルをアップロードするか、プランを変更してください。」 |
studio.data.rows.max | 組織の全データセットの行数 | 行 | 「このプランでは組織の全データセット合計で 250,000 行まで利用できます。データセットを削除するか、プランを変更して追加してください。」 |
文章中の数値は Free の上限です。実際のレスポンスには組織の上限値が入ります。ユーザーに文章を表示し、code と limit_key で処理を分岐してください。この 402 は AI クレジットに関するプラットフォーム API の 429 quota_exceeded とは異なります。
400 VALIDATION_ERROR
本文には 2 つのフィールドしかなく、問題詳細の追加要素はありません：
{
"error": "VALIDATION_ERROR",
"message": "File is larger than 64 MB."
}
| 拒否の理由 | message |
|---|---|
| ファイルが 64 MiB を超える | 「ファイルは 64 MB を超えています。」 |
| データセットが 100,000 行を超える | 「データセットごとの最大レコード数は 100000 です」 |
| 地理ファイルが 50,000 フィーチャーを超える | 「<filename> には 50000 個を超えるフィーチャーがあります。アップロード前に分割するかジオメトリを簡素化してください。」 |
| 画像オーバーレイが 16 MiB を超える | 「オーバーレイ画像は 16 MB を超えています。」 |
Studio が読み取れないファイル形式や、使用可能な行のないファイルなど、別の問題でも同じステータスとコードになります。具体的な理由は message に記されます。アップロード時の 400 はすべて「このファイルは現状のままでは追加できない」と扱い、message を表示してください。
関連ページ
- 認証とスコープ：認証情報とセッション交換。
- クォータとレート制限：429 レスポンスの詳細。
- SSE ワイヤー仕様：ストリーム上のイベント。
- トラブルシューティング：症状別の問題。