Idempotency
Send an Idempotency-Key header (8–128 characters [A-Za-z0-9_-], a UUID is fine) on every write. It is required on POST /businesses/:id/holds, POST /businesses/:id/bookings, POST /bookings/:id/payments, POST /bookings/:id/reschedule (400 BAD_REQUEST without it) and honoured on every other POST, PUT and PATCH.
The key is scoped to your principal and kept for 24 hours: a retry with the same key returns the original status and body — a hold is never taken twice, a payment never recorded twice. The same key with a different body answers 409 IDEMPOTENCY_MISMATCH.
POST /api/v1/businesses/ckbiz1/holds
Idempotency-Key: <one uuid per intent, e.g. per customer click>Choose one key per intent (one per customer click), not per HTTP attempt.