Squire SDK error handling and session state management

Robust error handling keeps your EHR integration reliable across patchy networks and unexpected server conditions. The Squire SDK provides a built-in state machine, automatic reconnection logic, and explicit error surfaces so you can respond appropriately at every stage of a consultation.

SDK state machine

Every consultation session moves through a defined set of states. Understanding these transitions helps you drive your UI — for example, showing a spinner during INITIALIZING or a warning banner during RECONNECTING. The possible state values are:

State	Description
`INITIALIZING`	The SDK is setting up the session and connecting to the microphone
`RECORDING`	Audio is actively streaming to the server
`PAUSED`	Recording is paused; the session remains open
`RECONNECTING`	The connection dropped; the SDK is retrying automatically
`AWAITING_SUMMARY`	Recording has stopped; the server is generating the report
`FINISHED`	The report is ready; the session is closed

Listen for state changes

Subscribe to the state-change event to receive every transition:

squire.on('state-change', (status) => {
  console.log('SDK status changed to:', status);
  // Update your UI based on the new status.
});

Built-in error handling

The SDK includes retry logic for transient errors such as network interruptions and server errors. If the connection drops while audio is streaming, the SDK enters the RECONNECTING state and continues buffering audio locally. Once the connection is re-established, all buffered audio is sent to the server — no data is lost. If the SDK encounters a non-recoverable error, it emits an error event:

squire.on('error', (error) => {
  console.error('Squire SDK error:', error);
  // Show an error notification to the user.
});

Explicit error handling

startRecording is asynchronous and may reject if the microphone is unavailable, permissions are denied, or the server cannot be reached. Wrap it in a try/catch block to handle these cases gracefully:

try {
  // Your logic to show a loading state goes here ...
  const consultation = await squire.startRecording();
  // Your logic to hide the loading state goes here ...
} catch (error) {
  // Your logic to handle errors goes here, e.g. show a notification to the user.
}

Report generation result

After a consultation completes, check the generation_result field in the summary to confirm the report was generated successfully. See the report generation result reference for the list of possible values and how to handle each one.

Log level

Log level configuration was introduced in SDK v1.8.1.

By default, the SDK logs at the info level. You can adjust this when initializing the SDK to get more or less output:

const squire = new Squire({
  token: 'REPLACE_WITH_ACCESS_TOKEN',
  outputLanguage: 'en',
  logLevel: 'debug',
});

Available log levels, from most to least verbose:

Level	Description
`debug`	Detailed debugging information
`info`	General operational information (default)
`warn`	Warnings about potential issues
`error`	Error messages only
`silent`	No logging output

Use debug during development to trace every SDK event, and switch to warn or error in production to reduce noise.

Get Started

SDK

Widgets

Output & Data

Reference

Squire SDK error handling and session state management

SDK state machine

Listen for state changes

Built-in error handling

Explicit error handling

Report generation result

Log level

​SDK state machine

​Listen for state changes

​Built-in error handling

​Explicit error handling

​Report generation result

​Log level

SDK state machine

Listen for state changes

Built-in error handling

Explicit error handling

Report generation result

Log level