Errors, empty results, and recovery

HealthBridge uses completion results for reads, writes, routes, and deletes. Design separate UI for failure, successful empty data, unsupported behavior, and permission recovery.

Result-handling pattern

1. Check bSuccess.
2. On failure, preserve the player’s current UI state.
3. Convert the SDK error into safe, actionable product copy.
4. On success, inspect the returned records or operation-specific fields.
5. Treat an empty successful read as a normal outcome.

Never display a raw native callback or JSON payload directly to the player.

Common states

State	Meaning	Response
Provider not ready	Initialization has not succeeded	Retry initialization or disable the feature
Unsupported capability	Active provider lacks the operation	Hide or explain the feature
Permission denied	Player declined required access	Explain how to review platform settings
Successful empty read	No visible records were returned	Show an empty state
Route consent required	Android requires route-specific action	Explain, request consent, then retry
Write failed	Record was not confirmed saved	Keep unsaved state and offer retry
Delete failed	Record remains in the platform store	Keep it visible and explain failure

iOS ambiguity

HealthKit does not disclose every read denial. bSuccess=true with no samples can mean no records or denied visibility. Avoid messages such as “You granted access but have no data.”

Android diagnostics

When a Health Connect permission is missing:

1. Check the configured permission row.
2. Inspect the final manifest declaration.
3. Confirm Health Connect is installed and current.
4. Review granted and denied permissions.
5. Retry only after a player action or settings change.

Logging policy

Safe diagnostics can include:

• Unreal and plugin versions.
• Platform and OS version.
• Operation name.
• Provider name.
• A sanitized error category.

Do not include health samples, timestamps tied to samples, routes, record IDs, session IDs, raw callbacks, or permission payloads containing private data.

Recovery checklist

• Make optional health features degradable.
• Keep unrelated gameplay available.
• Provide settings and retry actions.
• Stop monitoring and remove delegates during teardown.
• Ignore stale completions after their screen closes.