Error Handling

Proper error handling is essential for providing a good user experience. Squire SDK provides robust error handling mechanisms to ensure a smooth integration experience. This page covers both built-in and explicit error handling strategies, as well as log level configuration.

State Diagram

The sessions in the Squire SDK follow the state diagram below:

Listening for state changes

You can listen to state transitions using the state-change event. This event is emitted whenever the SDK transitions between states, allowing you to update your UI accordingly.

squire.on('state-change', (status) => {
  console.log('SDK status changed to:', status);
});

The possible status values are: INITIALIZING, RECORDING, PAUSED, RECONNECTING, AWAITING_SUMMARY, and FINISHED.

Error handling

Built-in Error Handling

The SDK includes built-in error handling and retry logic for transient errors, such as network issues or server errors. If a non-recoverable error occurs, an error event will be emitted.

If the connection drops during audio streaming of an active consultation, the SDK will attempt to reconnect automatically. During the RECONNECTING state, the client continues to buffer audio locally. Once the connection is re-established, all buffered audio is sent to the server, ensuring no data is lost.

Explicit Error Handling

The startRecording method processes asynchronously to set up a new session, connect to the microphone, and start streaming audio. If any error occurs during this process, the promise will be rejected with an error. You can handle these errors using a try-catch block:

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
}

API errors

When a request to the Squire API fails, the promise rejects with a Squire.ApiError. It extends Error, so error.message still holds a readable description, and adds the machine-readable parts of the response:

Both the error class and the codes are reachable as statics on the default export, so no named imports are needed. The codes to handle explicitly are:

Quota exceeded

import Squire from '@squirehealth/sdk';
 
try {
  const consultation = await squire.startRecording();
} catch (error) {
  if (
    error instanceof Squire.ApiError &&
    error.code === Squire.CONSULTATION_QUOTA_EXCEEDED
  ) {
    // Show an upgrade prompt instead of a generic error
    return;
  }
  throw error;
}

See Product usage for reading the remaining allowance and the date it resets.

Purged data

Organizations can set a data retention policy that permanently removes a consultation’s audio, transcript and report on a schedule. Once the transcript is gone, the report can no longer be regenerated, so splitSoap() and mergeSoap() reject with a Squire.ApiError carrying status: 410 and code === Squire.DATA_PURGED. When detail is set it names which data went, in wording written to be shown to the user, but it can be null, so keep a fallback message.

import Squire from '@squirehealth/sdk';
 
try {
  await consultation.splitSoap();
} catch (error) {
  if (error instanceof Squire.ApiError && error.code === Squire.DATA_PURGED) {
    // `detail` names which data went and is safe to show, but it can be null
    showMessage(error.detail ?? 'This consultation is no longer available.');
    return;
  }
  throw error;
}

This is a final state rather than a transient failure: the data is not coming back, so retrying the call will fail the same way. Present it to the user as such instead of offering a retry.

A consultation can outlive its report, so the same policy shows up in a summary: it comes back with report_status: "purged" and data: null. See Report status.

Report Generation Result

After a consultation is completed, check the generation_result field to ensure the report was generated successfully. See Report generation result for possible values and how to handle them.

Log Level

You can set the desired log level when initializing the Squire SDK by adding the logLevel option. The available log levels are:

• debug: Detailed debugging information.
• info: General operational information. (default)
• warn: Warnings about potential issues.
• error: Only error messages.
• silent: No logging output.

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