error field; most other failures, including denied access to a resource, use message.
Status codes
Response shapes
401 Unauthenticated
401 Unauthenticated
Returned when credentials are missing or invalid.
403 Forbidden
403 Forbidden
Either the key is missing a permission (
error) or access to the resource was denied (message).404 Not found
404 Not found
Unified failure envelope. On stack detail routes, another team’s stack is indistinguishable from a missing one.
422 Validation failed
422 Validation failed
errors maps field names to messages.422 Quota exceeded
422 Quota exceeded
Same status as validation, different body. Quota refusals do not return 402.
429 Too many requests
429 Too many requests
v1 operations include
Retry-After (seconds). See Rate limits.MCP errors
MCP JSON-RPC refusals use{ "jsonrpc": "2.0", "error": { "code", "message" } }. id is omitted on 401, 403, and 429 refusals made before the message is read.
Common JSON-RPC codes:
-32000— rate limited-32001— unauthorized-32002— subscription required (data.reason=subscription_required, plusdata.upgrade_url)

