오류
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 없음 / invalid / revoked / 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로도 차단됩니다. |
| 403 | ip_not_allowed | server key가 allowlist 외 IP에서 사용됨 | key의 IP allowlist를 업데이트하거나 허용된 address에서 호출하세요. |
| 403 | publishable_key_required | SDK session exchange가 publishable key가 아닌 값으로 시도됨 | session-exchange 단계에서 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 후 다시 시도하세요. |
| 429 | (flat) b2b_overloaded | global request-shedding 활성화 | back off 후 jitter를 적용해 다시 시도하세요. |
| 429 | (flat) org_overloaded | org별 shedding | back off 후 다시 시도하세요. |
| 429 | limiter_unavailable | rate limiter에 일시적으로 접근할 수 없음 | 일시적 문제로 처리하고 다시 시도하세요. |
| 429 | rate_limited | 현재 요청이 너무 많음 | Retry-After를 따르세요. |
| 503 | (no detail) | key service가 일시적으로 사용할 수 없음 | 일시적 문제 — 잠시 후 다시 시도하세요. |
키 관리
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 오류
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는 오류가 아닙니다 — 남은 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를 참조하세요.