Errors

Every error is one envelope:

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": [{ "field": "date", "issue": "must be YYYY-MM-DD" }], "requestId": "req_…" } }

HTTP	code	When
400	`BAD_REQUEST`	malformed JSON, bad cursor, missing `Idempotency-Key` where required
401	`AUTH_REQUIRED` · `AUTH_INVALID_TOKEN` · `API_KEY_REVOKED`	no, bad or revoked credentials
403	`ROLE_REQUIRED` · `SCOPE_MISSING` · `FORBIDDEN` · `READ_ONLY_MODE`	the principal may not do this (read-only: the business's subscription lapsed)
404	`NOT_FOUND`	unknown id — also another tenant's id
409	`NOT_AVAILABLE` · `ILLEGAL_TRANSITION` · `IDEMPOTENCY_MISMATCH` · `ALREADY_EXISTS`	the calendar is taken, the state machine refuses, a reused key with another body
422	`VALIDATION_FAILED` · `POLICY_VIOLATION`	the body failed validation; a business rule (details say which)
429	`RATE_LIMITED`	see Rate limits — honour `Retry-After`
503	`DEPENDENCY_UNAVAILABLE`	a provider or datastore is down; retry idempotently

Include the requestId when you write to support.