Errors

Each SDK has its own error type. This page lists what the released SDKs (Flutter 0.7.0, Kotlin 0.4.2, Swift 0.4.3) actually throw.

Flutter

`SynheartWearError`

class SynheartWearError implements Exception {
  final String message;
  final String? code;
  final Exception? originalException;
}

Thrown by	`code`	When
`initialize()`	`NO_WEARABLE_DATA`	No enabled adapter returned any data.
`initialize()`	`STALE_DATA`	The newest sample is more than 24 hours old.
`initialize()`, `readMetrics()`	—	Any other failure, wrapped with the cause in the message.
Cache calls	—	Cache read, write or encryption failed, or caching is disabled.

PermissionDeniedError (a SynheartWearError with code PERMISSION_DENIED) is thrown when the user denies the platform permission request. DeviceUnavailableError (DEVICE_UNAVAILABLE) and NetworkError (NETWORK_ERROR) are defined but not thrown by 0.7.0.

try {
  await synheart.initialize();
} on PermissionDeniedError {
  // Explain why the app needs access, then ask again
} on SynheartWearError catch (e) {
  switch (e.code) {
    case 'NO_WEARABLE_DATA': // nothing synced yet: ask the user to check their device
    case 'STALE_DATA':       // data older than 24 h: ask the user to sync
    default:                 // log e.message
  }
}

Cloud providers

WhoopProvider, GarminProvider, FitbitProvider and OuraProvider throw a plain Exception with a descriptive message (for example when userId is missing or the Synheart Wear API returns an error), and StateError for misuse. Catch Exception around provider calls.

BLE heart-rate monitors

BleHrmProvider throws BleHrmError, whose code is a BleHrmErrorCode: permissionDenied, bluetoothOff, deviceNotFound, subscribeFailed or disconnected. Unknown native errors map to subscribeFailed. Errors on the onHeartRate stream use the same type. See BLE Heart Rate Monitor.

Garmin Health SDK (RTS)

GarminHealth throws GarminSDKError subclasses, each a SynheartWearError with a GARMIN_* code: GarminInitializationError, GarminLicenseError, GarminScanError, GarminPairingError, GarminConnectionError, GarminStreamingError, GarminSyncError, GarminDataError and GarminPlatformError.

Apple Health XML import

Failures throw the sealed AppleHealthXmlError: ZipReadFailed, XmlNotFound, ParseFailed, IngestFailed or ImportCancelled.

Kotlin

SDK calls throw SynheartWearException(message, cause, code):

any call before initialize() (“SDK not initialized”);
initialize() failures, wrapped;
getProvider() when the vendor isn’t enabled or cloudConfig is missing;
every GarminHealth data call in the Maven Central build, which doesn’t include the licensed Garmin binary.

BLE calls throw BleHrmException, whose errorCode is a BleHrmErrorCode (PERMISSION_DENIED, BLUETOOTH_OFF, DEVICE_NOT_FOUND, SUBSCRIBE_FAILED, DISCONNECTED).

Swift

SDK calls throw SynheartWearError:

Case	When
`notInitialized`	A call before `initialize()`.
`healthKitNotAvailable`, `healthKitTypeNotAvailable`	HealthKit or a requested type isn’t available on this device.
`permissionDenied`	Access was refused.
`invalidData`, `cacheError(String)`	Bad data, or a cache failure.
`noConnection`, `timeout`, `hostUnreachable`, `invalidResponse`	Network failures reaching the Synheart Wear API.
`notConnected`, `authenticationFailed`, `tokenExpired`, `rateLimitExceeded`, `serverError(Int, String?)`, `apiError(String)`	Cloud provider failures. `apiError` is also thrown by `getProvider(_:)` when a vendor isn’t configured.
`bleHrm(BleHrmErrorCode, String)`	BLE heart-rate monitor failures.

The Apple Health XML import throws AppleHealthXmlError: zipReadFailed, xmlNotFound, parseFailed(line:column:message:), ingestFailed or cancelled.

Retries

The SDKs don’t retry cloud requests or back off on rate limits; handle retries in your app. The only automatic retry is BLE reconnection after an unexpected disconnect (see BLE Heart Rate Monitor).

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.

Wear Overview — config flags that influence error paths.
Adapters — per-vendor flow.
Data Schema — null-vs-missing semantics.

Get Started

Security

Setup

CLI

Synapse

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

Flutter

`SynheartWearError`

Cloud providers

BLE heart-rate monitors

Garmin Health SDK (RTS)

Apple Health XML import

Kotlin

Swift

Retries

Logging policy

Flutter

SynheartWearError

Cloud providers

BLE heart-rate monitors

Garmin Health SDK (RTS)

Apple Health XML import

Kotlin

Swift

Retries

Logging policy

Related

`SynheartWearError`