Errors, empty results, and recovery

Design distinct UI for failure, successful empty data, unsupported capability, and permission recovery.

Result pattern

1. Check Success.
2. Preserve current UI state on failure.
3. Convert SDK errors to safe, actionable product copy.
4. Inspect records only after success.
5. Treat an empty successful read as normal.

Never display raw native callbacks or payload JSON.

Common states

State	Response
Provider not ready	Initialize correctly or disable the feature
Unsupported capability	Hide or explain the operation
Android core permission denied	Offer Health Connect settings/retry guidance
Successful empty read	Show an empty state
Route consent required	Explain, request consent, then retry
Write failed	Preserve unsaved state and offer retry
Delete failed	Keep the record visible

iOS ambiguity

HealthKit can hide a declined read. A successful empty result does not prove permission or absence of records.

Async failure safety

• Await tasks; never block the Unity main thread.
• Catch exceptions at the feature boundary.
• Ignore stale completions after a screen or object closes.
• Unsubscribe static events during teardown.
• Keep optional health features degradable.

Safe diagnostics

Logs may include Unity/package version, platform/OS, operation name, provider, and a sanitized error category. Exclude samples, routes, record/session IDs, timestamps tied to private samples, and raw permission/native payloads.