Skip to main content
The wear SDK exposes a small typed error hierarchy. Most adapters emit one of three error subtypes; vendor-specific failures bubble through originalException.

​
Base type

Subtypes: originalException carries the platform-specific underlying error so callers can inspect when the typed code is too coarse.

​
Permission denied

Triggered by:
  • HealthKit refusing access to a requested HKObjectType.
  • Health Connect missing a permission grant for HeartRateRecord (etc.).
  • BLE permission revoked at OS level.
  • Vendor OAuth flow cancelled by user or rejected by vendor.
  • requestPermissions returning denied for any requested type.
Recovery:
  • For OS permissions: surface a UI rationale and call requestPermissions again with the missing types.
  • For OAuth: route the user back through the vendor’s auth URL.
  • For revoked permissions: the SDK reports ConsentStatus.revoked, distinct from denied (never granted vs previously granted).

​
Device unavailable

Triggered when the adapter cannot find a viable data source:
  • HealthKit not present (iPad without paired iPhone).
  • Health Connect not installed or unsupported on the Android version.
  • BLE HRM scan times out without finding a 0x180D device.
  • Vendor webhook subscription not active.
  • streamHR invoked while no underlying source is connected.
Recovery: the SDK retries on streamHR/streamHRV reconnects, but readMetrics() calls fail fast. Hosts should display a “no device connected” UI and let the user reconnect.

​
Network error

Triggered by HTTP/RPC failures in the cloud adapters (WHOOP, Garmin, Fitbit). The originalException wraps the underlying transport error. Common causes:
  • Vendor token expired (caller should refresh OAuth).
  • Vendor rate-limit (HTTP 429); adapters back off.
  • Server-side outage (5xx).
  • TLS validation failure.
Recovery: per-adapter, with exponential backoff. Token-related failures may surface as PermissionDeniedError instead, depending on the vendor.

​
Adapter-specific errors

​
HealthKit

The SDK maps these to PermissionDeniedError or DeviceUnavailableError as appropriate.

​
Health Connect

The SDK surfaces these as DeviceUnavailableError (install/migration) or PermissionDeniedError (permissions).

​
BLE HRM

​
WHOOP (cloud)

​
Garmin (cloud)

​
Garmin Health SDK (RTS)

​
Apple Health XML backfill

​
Logging policy

The SDK logs at info/warn and never logs:
  • Vendor OAuth tokens.
  • Personal device_ids in plain (debug builds may; production ones do not).
  • Raw HRV/RR sample bytes.
  • XML payloads beyond malformed-record line numbers.
WearMetrics snapshots are not logged. Hosts that need observability should collect them at the consumer layer.

​
Validation invariants

Regardless of error state:
  • WearMetrics.timestamp is always UTC ISO-8601.
  • Numeric metric values are finite (NaN/inf get filtered to null).
  • Event ordering is preserved within a single adapter; cross-adapter ordering uses timestamp.