Error States Reference

How Hygate handles error conditions across modules.

Guest-Facing Error States

Error	Condition	What Guest Sees	Resolution
Door in Maintenance	Door status = MAINTENANCE	"Currently Closed for Maintenance" message	Admin changes door status to Active
Door in Passage Mode	Door status = PASSAGE	"Free Access" — no payment required	No action needed; guest enters freely
Device in Maintenance	Device status = MAINTENANCE	"Device Currently Unavailable"	Admin changes device status to Active
Device in Use	Another session is ACTIVE on the same device	"Device is currently in use. Please try again later."	Wait for existing session to end
Payment Failed	Card declined or Stripe error	"Your payment could not be processed."	Guest tries a different card
3D Secure Failed	Guest failed bank verification	Redirected back to payment page	Guest retries or uses different card
Invalid Door/Device	Door/device uid not found	"Access point not found"	Check door/device UID configuration
Webhook Timeout	Stripe webhook not received	Payment may show PENDING	Stripe retries webhook delivery

State	Condition	Display	Guest Action
Loading	Initial page load	Skeleton/loading animation	Wait
Running	Session is active with time remaining	Countdown circle in primary color	Use the device
Finishing	Time remaining = 0, waiting for relay OFF	Countdown circle, timer at 0:00	Wait for relay OFF confirmation
Complete	Timer finished, relay OFF	Green checkmark, "Session Complete"	Done
Interrupted	Session cancelled after starting	Amber indicator, "Session Ended"	Contact support
Failed to Start	Session cancelled before relay turned on	Red indicator, "Session Could Not Start"	Contact support
Unavailable	Device went offline during session	Red indicator, "Device Unavailable"	Contact support

Indicator	Cause	Check
TTLock red	Connection failed, invalid credentials	Settings → TTLock → Test Connection
Shelly red	Auth key invalid, service down	Settings → Shelly → Test Connection
Stripe red	API keys invalid, webhook misconfigured	Settings → Stripe → Test Connection
No active sessions	Normal if no device sessions active	Doors still work normally
Zero revenue	No payments yet, or test mode active	Normal for new installations

Error	Cause	Fix
Sync returns no locks	TTLock credentials wrong, account has no locks	Verify TTLock credentials and lock ownership
QR code generation fails	TTLock API unavailable	Retry; check TTLock API status
Status won't change	Permission issue	Operators may be restricted; check role
Delete fails	Foreign key constraint	Remove associated data first

Error	Cause	Fix
Power ON fails	Shelly device offline, network issue	Check device connectivity in Shelly app
Power ON fails after 3 retries	Device unreachable	Mark session as CANCELLED; check device
Power OFF fails	Shelly API issue	Retry; cron job will attempt again in 2 minutes
Sync returns no devices	Shelly Auth Key wrong	Re-enter Auth Key in Settings → Shelly
Session stuck on "Finishing"	Relay OFF command pending	Wait 5 minutes (cleanup cron) or click Force End

Error	What Happens	Fix
Duplicate webhook	Hygate detects existing payment, ignores webhook	Normal — idempotency working
Payment succeeded but no session	Webhook received but session creation failed	Check audit logs; manually create session
Wrong price charged	Price locked at payment initiation	Refund via Stripe; re-purchase at correct price
Webhook not received	Stripe can't reach Hygate endpoint	Check HTTPS, webhook URL, firewall

When Hygate restarts, it performs recovery on all active sessions:

Scenario	Recovery Action
Session expired during downtime	Relay OFF → COMPLETED
Session valid, relay ON	Confirm → no change
Session valid, relay OFF (interrupted)	Mark CANCELLED with reason

All recovery actions are logged with the startup_recovery event.

The 2-minute reconciliation process detects state mismatches:

Mismatch	Action
Session ACTIVE, relay OFF	Mark CANCELLED
Session expired, still ACTIVE	Force complete
Session not found, relay ON	Log warning (orphan relay state)

Reconciliation logs contain the reconciliation event with before/after state.

Scenario	Hygate Behavior
ON command fails	3 retries (5s each) → mark session CANCELLED → log `shelly_on_failed`
OFF command fails	3 retries → log error → retry on next cron cycle
4xx response on OFF	Treat as non-fatal (already off)

Code	Meaning	Common Cause
400	Bad Request	Invalid request data, validation failure
401	Unauthorized	Missing or expired JWT
403	Forbidden	Insufficient role permissions
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource, state conflict
500	Internal Error	Unexpected server error
502	Bad Gateway	Upstream service (Stripe, TTLock, Shelly) unavailable
503	Service Unavailable	Hygate server overloaded or maintenance

Check Sessions — was a session created?
Check Audit Logs for shelly_on_requested → shelly_on_success or shelly_on_failed
If relay ON failed → check Shelly device connectivity
Navigate to session → try manual retry activation
If all else fails → click Force End and investigate root cause