Errors

A single error shape with stable machine-readable codes.

Every error returns a consistent JSON envelope with a stable code (branch on this) and a human message (show this).

json

{
  "error": {
    "code": "missing_scope",
    "message": "This key is missing the required scope.",
    "details": {}
  }
}

Common codes

HTTP	code	Meaning
401	`api_key_required`	No key supplied
401	`api_key_invalid`	Key not recognised
401	`api_key_revoked` / `api_key_expired`	Key no longer valid
402	`free_trial_expired`	Subscription/trial lapsed
403	`missing_scope`	Key lacks the required scope
409	`idempotency_key_conflict`	Same key, different body
409	`cap_reached`	Per-workspace limit hit
429	`rate_limited`	Too many requests

Always branch on code, not the human message - messages may change, codes are stable.