Troubleshooting

Incident triage (first 10 minutes)

1. Classify impact: read-only, write-path, or data-risk.
2. Isolate lane: API, DB, Queue/Worker, Auth.
3. Capture evidence: request id, timestamp, actor, endpoint.
4. Apply safest stabilizing fix first.

Quick diagnosis table

Symptom	Fast check	Likely root cause	First fix
404 route	php artisan route:list	wrong prefix/group in api file	align route declaration + clear route cache
401 auth	check bearer/session guard	token mismatch or wrong guard	verify sanctum/auth config and middleware
422 validation	inspect response errors	payload contract mismatch	sync request shape with endpoint contract
Reservation save fails	DB logs + transaction trace	deadlock/constraint violation	retry with backoff; review transaction scope
Queue not processed	php artisan queue:failed	worker down/config mismatch	restart worker + replay failed jobs

Escalate immediately when

• Potential data loss/corruption
• Repeated production deadlock burst
• Auth bypass suspicion
• Queue replay causing duplicate irreversible side-effects