Errors

Platform API failures use standard HTTP status codes.

Status	Meaning	What to do
401	Missing / invalid / revoked / expired key	Check the key value and that it isn't revoked. The viewer product needs no key.
403 insufficient_scope	Valid key, but lacks the route's scope	Mint / re-mint a key with the right scope (ai / maps / design).
422	Malformed request body	Fix the payload (see Endpoints for shapes). On mint, unknown_scope / unknown_product mean an out-of-vocabulary value; publishable_live_requires_origins means a live publishable key was minted with no allowed origins.
429	Either the org's monthly quota (b2b.tokens, or map_load_quota_exceeded for basemap sessions) or a short-term limit — rate_limited for too many requests right now, or a shed concurrency slot	Back off and retry, honouring Retry-After where present; surface "upgrade" in your UI for the monthly case, which is the one carrying a meter in the body. See Quota.
503	Key service temporarily unavailable	Transient — retry shortly.

Credential-family specifics

When you use the newer publishable / server keys, a few subcodes narrow the cause:

Status	Subcode	Cause
401	publishable_requires_session	A publishable key (kld_pk_…) was sent as a direct bearer. Use it through the SDK, which exchanges it for a session.
403	origin_required	A publishable key was used without a browser Origin (e.g. server-side). Publishable keys are browser-only.
403	origin_not_allowed	The request Origin isn't in the key's allowed-origins list.
403	product_not_allowed	The key isn't permitted for this product (chat / editor / tile).
403	server_key_in_browser	A server key (kld_sk_…) was used from a browser (a request Origin was present). Server keys are server-side only.
403	publishable_key_required	The SDK session exchange was attempted with something other than a publishable key.
403	free_plan_publishable_only	A Free-plan org tried to mint a server key. Free keys are publishable, basemap-only.
429	map_load_quota_exceeded	The org's monthly map-loads allowance is spent (basemap sessions).
429	map_load_hard_stop	A paid org is five times past its map-loads allowance. Serving stops here; the soft band above the allowance keeps working. See Quota.

Server keys used from a browser are also CORS-blocked (no Access-Control-Allow-Origin) — keep them server-side. Key management (creating / rotating / revoking keys) is done by an org owner/admin in the dashboard, not with a key.

Streaming errors

On an SSE stream, a terminal failure arrives as an error event rather than an HTTP status (the response already started 200):

event: error
data: { "message": "…" }

Treat an error event as the end of that stream. A mid-stream quota event is not an error — it's the meter telling you how much budget remains.

CORS "blocked" in the browser

If the browser reports a CORS block on a real request, the request Origin isn't in the key's allowed-origins list — not an auth failure. See CORS & allowed origins.