错误

Platform API 失败使用标准 HTTP 状态码。几乎每次失败都包含一个稳定的 subcode 字符串，客户端应基于它进行分支 — 单独依赖状态码会产生歧义 （403 同时涵盖 scope、产品、origin、IP 和密钥类型）。

Envelope

大多数错误都会返回 FastAPI 风格的 detail wrapper：

{ "detail": "<subcode>" }

结构化的 429 payload（map_load_quota_exceeded, b2b_overloaded, org_overloaded, tile_access_restricted）是位于顶层的扁平对象 — 没有 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" }

某些非 streaming endpoint 会以 HTTP 200 加 error key 的形式报告失败 — 最典型的是 POST /chat/control/route。如果只根据 status 分支，就会将其视为成功。请始终读取 body。

表格

状态	Subcode	含义	处理方式
401	(no detail)	密钥缺失 / 无效 / 已撤销 / 已过期	检查密钥值，并确认未被撤销。Viewer 不需要密钥。
401	publishable_requires_session	publishable key（kld_pk_…）被作为 direct bearer 发送	通过 SDK 使用它，由 SDK 将其交换为 session。
403	insufficient_scope	密钥有效，但缺少 route 所需 scope	创建 / 重新创建具有正确 scope（ai / maps / design）的密钥。
403	tier_capability_not_allowed	已存储的 key 曾经拥有该 capability，但组织当前 tier 已不再允许（通常是 Pro→Free downgrade）	升级套餐，或使用当前 tier 允许的产品。
403	origin_required	publishable key 在没有浏览器 Origin 的情况下使用（例如服务端）	publishable key 仅限浏览器使用。
403	session_origin_mismatch	请求 Origin 不在 key 的 allowlist 中	更新 key 的 allowed origins（参阅 获取 API 密钥）。
403	product_not_allowed	key 不允许用于此产品	创建允许该产品的 key（或使用无需密钥的 viewer）。
403	server_key_in_browser	server key（kld_sk_…）从浏览器使用	server key 仅限服务端；同时会被 CORS 阻止。
403	ip_not_allowed	server key 从 allowlist 外的 IP 使用	更新 key 的 IP allowlist，或从允许的地址调用。
403	publishable_key_required	SDK session exchange 使用了 publishable key 以外的内容	在 session-exchange 步骤使用 kld_pk_… key。
403	sessions_disabled	此 deployment 禁用了 session 发放	联系支持 — 这是运行状态，不是客户设置。
403	sessions_not_configured	session infrastructure 尚未配置	联系支持。
422	(various)	请求 body 格式错误	修复 payload（参阅 Endpoints）。mint 时，unknown_scope / unknown_product 表示未识别值；publishable_live_requires_origins 表示 live publishable key 在没有 allowed origins 的情况下被 mint。
429	(flat) map_load_quota_exceeded	组织每月 map-loads 配额已用尽	升级套餐或减少底图加载。
429	map_load_hard_stop	付费组织超过 map-loads 配额 5×	此处停止服务；配额以上的 soft band 在达到该点前仍可工作。
429	(flat) tile_access_restricted	Tile 请求被拒绝（通常是 origin allowlist 不匹配）。包含 Retry-After: 3600	将页面 origin 添加到 key allowlist；在 header 指定时间后重试。
429	(flat) b2b_overloaded	全局 request-shedding 已启用	降低请求频率，并加入 jitter 后重试。
429	(flat) org_overloaded	组织级 shedding	降低请求频率并重试。
429	limiter_unavailable	rate limiter 暂时不可访问	视为临时错误并重试。
429	rate_limited	当前请求过多	遵循 Retry-After。
503	(no detail)	密钥服务暂时不可用	临时错误 — 稍后重试。

密钥管理

来自 POST/PATCH/DELETE /shared-api/api-keys/* 的失败（使用 Cognito org-admin JWT，而不是 platform key）：

状态	Subcode	含义
403	free_plan_publishable_only	Free-tier 组织只能创建 publishable key。
403	plan_required	组织没有可识别的 API plan 记录。
403	tier_capability_not_allowed	PATCH 尝试将 key 扩展到组织当前 tier admission 之外。
403	vendor_scope_requires_acknowledgement	vendor scope 需要每个 key 显式设置 acknowledgement flag。
409	key_limit_reached	组织已达到其套餐允许的每组织 key 数量上限。

完整的 mint 流程和 PATCH 更新路径请参阅 获取 API 密钥。

Streaming 错误

在 SSE stream 中，终止性失败会以 error event 的形式出现，而不是 HTTP status（因为 response 已经以 200 开始）：

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

将 error event 视为该 stream 的结束。stream 中途出现的 quota event 不是错误 — 它只是告诉您还剩多少 budget 的 meter。 客户端必须忽略未知 event name — 在稳定 contract 内可以不升级版本就 添加新 event。

浏览器中的 CORS "blocked"

如果浏览器在真实请求中报告 CORS block，则请求 Origin 不在 key allowlist 中 — 这不是 auth failure。请参阅 CORS & allowed origins。