Error Handling

When interacting with the Eixam Connect SDK, exceptions are thrown to indicate configuration errors, network failures, or invalid state.

You should always wrap SDK calls in try-catch blocks and handle specific Eixam exceptions appropriately.

Common Exceptions

The SDK surfaces strongly-typed exceptions to help you identify the failure mode.

Exception	Cause	Resolution
UnsupportedError	EixamConnectSdk.bootstrap(...) was called without importing the Flutter package entrypoint that registers the bootstrapper.	Import package:eixam_connect_flutter/eixam_connect_flutter.dart before calling bootstrap.
ArgumentError	Invalid bootstrap config, such as empty appId, missing custom endpoints for custom, or initialSession.appId mismatch.	Validate config before bootstrap and keep appId consistent.
AuthException	The active signed session is missing, invalid, expired, or rejected.	Clear the session and fetch a new signed session from your backend.
NetworkException	The SDK could not reach the API or realtime transport.	Check connectivity and retry with backoff where appropriate.
TransportSecurityException	A custom endpoint or transport violates SDK security policy.	Use approved HTTPS/TLS endpoints; allow insecure local endpoints only in controlled local development.
DeviceException	Device pairing, activation, BLE command, or device runtime state is invalid for the attempted operation.	Check permissions, Bluetooth state, connection state, and command readiness before retrying.
FirmwareUpdateException	OTA preparation, artifact verification, native transfer, or installed-version verification failed.	Continue from the terminal firmware state and inspect requiresRecovery when present; do not assume retry is safe.
SosException / SosHttpException	SOS state, transport, or HTTP fallback failed.	Inspect code, message, and statusCode when present; show a recoverable flow when another SOS channel remains available.
TrackingException	Location/tracking state or permission is invalid.	Check location permissions and tracking state.
ContactsException / ContactsHttpException	Contact list or mutation failed.	Inspect HTTP fields on ContactsHttpException; refresh contact state after successful mutations.
DeathManException	DMP scheduling/check-in/cancel state is invalid.	Refresh the active plan and retry from the latest state.
ProfileHttpException	SDK profile GET/PUT /v1/sdk/me failed.	Inspect HTTP fields and fieldHints; map field hints into form errors.
FeedbackException / FeedbackHttpException	Authenticated feedback submission failed.	Check the current Eixam user JWT and inspect HTTP/API fields; SDK HMAC auth alone is insufficient.

Exceptions vs typed terminal state

Not every unsuccessful operation throws. Long-running or multi-path flows expose typed state so the host can render a deterministic result:

Flow	Typed result
Firmware update	FirmwareUpdateSession / FirmwareUpdateProgress with blocked, failed, cancelled, or recoveryRequired
LoRa radio region	DeviceCountryConfigStatus.outcome, plus applyAttempted and canRetry
Authoritative SOS	SosActivationResult, SosCancellationResult, and SosLifecycleSnapshot
Permission preflight	EixamPermissionPreflightResult

Use exceptions for call/transport failure and typed terminal state for the workflow outcome. Do not reduce either to a generic error toast.

Profile HTTP (GET/PUT /v1/sdk/me)

For fetchSdkUserProfile() and updateSdkUserProfile(), failures are surfaced as ProfileHttpException (extends EixamSdkException). Inspect:

Field	Use
statusCode	HTTP status from the platform
code	SDK-side classification code on the exception
message	Human-readable summary
apiErrorCode / apiErrorMessage	Parsed platform error envelope when present
fieldHints	List of SdkProfileApiFieldHint tying backend messages to name, email, phone, or address when the API provides field-level hints
rawBody	Optional raw response body for diagnostics

Prefer mapping fieldHints onto your form fields for inline errors; fall back to apiErrorMessage or message for banner-level messaging. For invalid payloads, validate locally first using SdkProfileValidators so you can avoid round-trips when fields violate documented constraints (length, E.164 phone, email format).

See also: Get SDK user profile, Update SDK user profile.

Emergency contacts HTTP (/v1/sdk/contacts)

Contact list and mutation failures are surfaced as ContactsHttpException (extends EixamSdkException) when the SDK HTTP layer can classify the response. Typical mappings:

HTTP status	SDK code (examples)	When
400	E_SDK_CONTACTS_VALIDATION	Invalid body, unknown id, or incomplete reorder payload (must include every contact id exactly once)
401	E_SDK_CONTACTS_UNAUTHORIZED	Missing/invalid signed session for SDK HTTP
404	E_SDK_CONTACTS_NOT_FOUND	Update/delete for a contact that does not exist for the user

Inspect statusCode, code, message, and optional apiErrorMessage for user-visible copy. Prefer refreshing listEmergencyContacts() / watchEmergencyContacts() after a successful reorder or delete so UI matches the server.

Diagnosing Real-Time Issues

For MQTT/real-time specific failures, use sdk.watchOperationalDiagnostics() to observe transport-level states without throwing exceptions directly into the UI.

sdk.watchOperationalDiagnostics().listen((diagnostics) {
  if (diagnostics.connectionState != RealtimeConnectionState.connected) {
    debugPrint('Warning: Real-time telemetry is degraded.');
  }
});

Device maintenance failures

• For OTA, keep the device nearby and continue observing through reconnect and verification. recoveryRequired needs the deployment-approved recovery path; see Firmware Updates / OTA.
• For regional configuration, detection-only skips should usually stay silent. Show an apply error only when applyAttempted is true, and offer retry only when canRetry is true; see LoRa Radio Region.