エラー

Platform API の失敗は標準 HTTP status code を使用します。ほぼすべての失敗に、client が 分岐に使用すべき安定した subcode string が含まれます — status code だけでは 曖昧です（403 は scope、product、origin、IP、key type を含みます）。

Envelope

ほとんどの error は FastAPI 形式の detail wrapper を返します：

{ "detail": "<subcode>" }

構造化された 429 payload（map_load_quota_exceeded, b2b_overloaded, org_overloaded, tile_access_restricted）は top level の flat object で、 detail wrapper はありません：

{ "error": "map_load_quota_exceeded", "meter": "map_loads", "limit": 50000, "used": 50000 }

String-detail 形式の 429（map-load hard stop）は wrapper を維持します：

{ "detail": "map_load_hard_stop" }

一部の non-streaming endpoint は失敗を error key を持つ HTTP 200 として 返します — 特に POST /chat/control/route です。status だけで分岐すると 成功として扱ってしまいます。必ず body を読んでください。

表

Status	Subcode	意味	対応
401	(no detail)	key がない / 無効 / revoke 済み / expired	key の値と revoke されていないことを確認してください。Viewer は key 不要です。
401	publishable_requires_session	publishable key（kld_pk_…）が direct bearer として送信された	SDK 経由で使用し、session と交換してください。
403	insufficient_scope	有効な key だが route に必要な scope がない	正しい scope（ai / maps / design）を持つ key を mint / re-mint してください。
403	tier_capability_not_allowed	保存済み key は capability を 持っていた が、org の現在の tier では許可されなくなった（通常 Pro→Free downgrade）	plan を upgrade するか、現在の tier が許可する product を使用してください。
403	origin_required	publishable key が browser Origin なしで使用された（例：server-side）	publishable key は browser 専用です。
403	session_origin_mismatch	request Origin が key の allowlist にない	key の allowed origins を更新してください（APIキーを取得 参照）。
403	product_not_allowed	key がこの product に許可されていない	product が許可された key を mint してください（または keyless の viewer を使用）。
403	server_key_in_browser	server key（kld_sk_…）が browser から使用された	server key は server-side 専用で、CORS でも block されます。
403	ip_not_allowed	server key が allowlist 外の IP から使用された	key の IP allowlist を更新するか、許可された address から呼び出してください。
403	publishable_key_required	SDK session exchange が publishable key 以外で試行された	session-exchange step では kld_pk_… key を使用してください。
403	sessions_disabled	この deployment では session 発行が無効	support に連絡してください — 顧客設定ではなく運用状態です。
403	sessions_not_configured	session infrastructure が設定されていない	support に連絡してください。
422	(various)	request body が不正	payload を修正してください（Endpoints 参照）。mint 時の unknown_scope / unknown_product は未認識値を意味します。publishable_live_requires_origins は live publishable key が allowed origins なしで mint されたことを意味します。
429	(flat) map_load_quota_exceeded	org の月間 map-loads allowance を使い切った	upgrade するか basemap load を減らしてください。
429	map_load_hard_stop	有料 org が map-loads allowance の 5× を超過	ここで配信停止。allowance を超えた soft band はそれまでは動作します。
429	(flat) tile_access_restricted	Tile request が拒否された（通常は origin allowlist 不一致）。Retry-After: 3600 を含む	page origin を key allowlist に追加し、header interval 後に retry してください。
429	(flat) b2b_overloaded	global request-shedding が有効	back off し、jitter を入れて retry してください。
429	(flat) org_overloaded	org 単位の shedding	back off して retry してください。
429	limiter_unavailable	rate limiter が一時的に到達不能	transient として扱い、retry してください。
429	rate_limited	現在 request が多すぎる	Retry-After に従ってください。
503	(no detail)	key service が一時的に利用不能	transient — 少ししてから retry してください。

Key management

POST/PATCH/DELETE /shared-api/api-keys/* からの失敗（Cognito org-admin JWT を使用。platform key ではありません）：

Status	Subcode	意味
403	free_plan_publishable_only	Free-tier org は publishable key のみ mint できます。
403	plan_required	org に認識済み API plan row がありません。
403	tier_capability_not_allowed	PATCH が org の現在の tier admission を超えて key を拡張しようとした。
403	vendor_scope_requires_acknowledgement	vendor scope には key ごとの明示的な acknowledgement flag が必要です。
409	key_limit_reached	org が plan の per-org key limit に到達しました。

完全な mint flow と PATCH update path は APIキーを取得 を 参照してください。

Streaming error

SSE stream では、terminal failure は HTTP status ではなく error event として到着します （response はすでに 200 で開始済みです）：

event: error
data: { "type":"error", "message":"…", "code":"…", "partial_text":"…" }

error event はその stream の終了として扱ってください。stream 途中の quota event は error ではありません — 残り budget を示す meter です。 client は未知の event name を無視する必要があります — stable contract 内では version bump なしで 新しい event が追加される場合があります。

Browser で CORS が "blocked"

実際の request で browser が CORS block を報告する場合、request Origin が key allowlist にありません — auth failure ではありません。 CORS & allowed origins を参照してください。