Errors

The SDK throws typed errors so you can branch on failure precisely. All of them extend SparkError, so a single instanceof SparkError catch handles anything the SDK throws.

SparkError

Base class for every SDK error. Catch it to handle all SDK failures uniformly.

import { SparkError } from '@epilot/spark-sdk'

try {
  await initialize()
} catch (err) {
  if (err instanceof SparkError) {
    // any SDK-originated failure
  }
}

SparkTimeoutError

Thrown when initialize() (or any bridge request) doesn't get a response within its timeout (default 5000ms). Carries the operation name and the timeout that elapsed.

import { initialize, SparkTimeoutError } from '@epilot/spark-sdk'

try {
  await initialize({ timeout: 8000 })
} catch (err) {
  if (err instanceof SparkTimeoutError) {
    console.error(`${err.operation} timed out after ${err.timeout}ms`)
    // show a "couldn't reach the portal" state, offer retry
  }
}

SparkNotInitializedError

Thrown when you call something that needs a session (getSession(), getEntity, executeUseCase) before initialize() has resolved. The fix is always to await initialize() first, or guard with isInitialized().

import { getSession, SparkNotInitializedError } from '@epilot/spark-sdk'

try {
  const session = await getSession()
} catch (err) {
  if (err instanceof SparkNotInitializedError) {
    // initialize() hasn't completed yet
  }
}

Handling failures in practice

In a React block, the cleanest place to handle connection failures is the session provider: catch at the bootstrap and render an error state. A HEMS does exactly this (spark-session-provider.tsx):

try {
  const session = await initialize()
  setStatus({ kind: 'ready', session })
} catch {
  setStatus({ kind: 'error' }) // renders a Callout instead of the app
}

For use-case failures, remember the distinction:

• Rejected promise → the call itself failed (network, timeout, not initialized). Catch it.
• result.success === false → the use case ran but the integration returned an error. Inspect result.error (and consider parsing it into a typed error, as a HEMS does with parseConnectApiError).