Salon/docs/runbooks/booking_failures.md

Runbook: Booking Failures

Summary

Guide for diagnosing booking creation or status update failures (availability, overlap prevention, or validation errors).

Symptoms

• POST /api/bookings/ returns HTTP 400 or 500.
• PATCH /api/bookings/<id>/ fails when confirming or cancelling.
• Users report bookings not appearing or incorrect status.

Impact

• Customers cannot place bookings.
• Staff schedules become inconsistent.
• Notification and payment flows may not trigger.

Quick Checks

• Confirm the request payload includes a valid service, staff, and scheduled time.
• Check server logs for booking validation errors or integrity exceptions.
• Verify that staff availability and overlap prevention rules are behaving as expected.

Mitigation Steps

• Reproduce with a known test user and staff member to isolate data issues.
• If overlap rules are too strict, review booking validation logic and confirm time zone assumptions.
• If status updates are blocked, verify role checks and serializer permissions in backend/apps/bookings/.
• If notifications are expected but missing, confirm NOTIFICATION_PROVIDER configuration and notification records.

Rollback / Escalation

• Roll back recent booking-related changes if failures started after a deployment.
• Escalate to engineering with the booking ID, user ID, and timestamps.

Notes

• Booking validation and status transitions live in backend/apps/bookings/.
• Notifications for booking lifecycle are handled in backend/apps/notifications/.