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.
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.
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.

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) {
    print('Warning: Real-time telemetry is degraded.');
  }
});