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_tier / unknown_scope mean an out-of-vocabulary value.
429	Over the org's monthly quota, or a concurrency slot was shed	Back off and retry; surface "upgrade" in your UI. 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.

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.