The troubleshooting model
Start with the observed state: time, tenant, role, the affected object, the expected result, the actual result, and the recent change. Then classify the issue as configuration, permission, provider, application, data, or infrastructure, and choose the smallest reversible action. Retry only when the operation is safe and idempotent; if a record may have duplicated, reconcile before retrying; if the system is rate-limited, respect the retry signal.
$ curl -s https://your-deployment.example.com/api/public/healthz
{
"status": "ok",
"db": "ok",
"db_ms": 4,
"uptime_ms": 2147841029,
"ts": 1787011200000
}A healthy healthz answers with its own state — platform status, a live database check with latency, and uptime. If db is not ok, the problem is below the application; if the endpoint itself does not respond, the problem is at the edge or the process. From there the ladders below move outward from the symptom.
Slot not offered
- Goal
- A customer expects a slot that does not appear.
- Action
- Check the availability dimensions in order: service duration, staff schedule and overrides, required resources, existing bookings, location schedule, timezone.
- Result
- One dimension rejects the window — fix that configuration rather than working around it.
Booking creation fails
- Goal
- A booking cannot be created.
- Action
- Read the typed error. Check the five rejection classes: not offered, not available, not permitted, provider unavailable, configuration incomplete.
- Result
- The error names the boundary that rejected the request; recovery follows the class.
Reminder not delivered
- Goal
- A customer did not receive an expected reminder.
- Action
- Open the notification log: check the message status (pending/sent/failed/suppressed/cancelled), the channel's rate state, and the tenant's enabled channels. Remember that SMS-opted-out customers are skipped except for the booking_created wave.
- Result
- A failed status shows exhaustion of the retry budget; a suppressed status shows a policy skip. Fix the channel configuration or accept the policy outcome.
Calendar out of sync
- Goal
- A staff calendar does not reflect bookings.
- Action
- Check the staff member's Google connection status, run sync-now, and verify the booking's state (cancelled bookings remove their events). For external feeds, verify the feed URL still serves and resync.
- Result
- Google events reflect QUE state; feed events reflect the external source.
Payment status not updating
- Goal
- A paid booking still shows pending.
- Action
- Verify the inbound webhook secret is configured (unset → endpoint reports unavailable), check the delivery history for the Stripe webhook, and reconcile from the booking's stored provider session reference.
- Result
- Payment status reflects what the provider's signed event reported.
Outbound webhook not firing
- Goal
- Events are not reaching an endpoint.
- Action
- Walk the chain in order: (1) webhook enabled and subscribed to the event (or *); (2) delivery history for response codes; (3) if a secret is set, re-test with signature verification — a receiver that rejects an invalid signature is actually working correctly; (4) re-test the endpoint from the webhook record.
- Result
- Delivery history shows each attempt's response, including the 60-second retry cadence; a repeatedly failing endpoint stays visible rather than silently dying.
Domain not verifying
- Goal
- A custom booking domain stays unverified.
- Action
- Re-check the DNS records the verification asked for (exact host, exact value), then request re-verification through the domain record. Remember unverified domains never serve traffic by design.
- Result
- Verification passes and the domain serves the booking surface.
Self-hosted deployment unhealthy
- Goal
- A self-hosted fleet misbehaves.
- Action
- Hit /api/public/healthz (status, db check, db_ms, uptime) and /api/public/metrics (with the bearer token). Walk the stack: database connection, Redis reachability, application logs through Loki, alert counts through the Alertmanager sink counters.
- Result
- The failure lands in one layer — configuration, permission, provider, application, data, or infrastructure — and the smallest reversible fix applies.
Exit conditions
An incident is not resolved when the screen loads once. Confirm the record, the audit trail, the operator view, the customer-facing state, and the monitoring signal. Record what changed, and whether a follow-up task is owed.