Error Handling

Quick summary

The Suki Headless SDK exposes error codes for authentication, session lifecycle, and other operations. All errors include an error code, name, and optional reason to help you diagnose issues and implement the correct handling logic.

Use this guide to understand what each error code means and how to resolve it in your application.

Last updated:September 2026

This guide details the error codes exposed by the Suki Headless SDK. Use this guide to diagnose issues and implement the correct handling logic in your application. Use the following type of errors to find the error code you need to handle while using the Suki Headless Web SDK.

Authentication Errors

Session Lifecycle Errors

Interoperability Errors

Pausing Session

Resuming Session

Cancelling Session

Submitting Session

Context Update Errors

Authentication errors (AuthError)

These errors occur during user registration, sign-in, or token updates.

Error code	Cause	Solution
`InvalidPartnerDetails`	You provided incorrect details during user registration.	Double-check your `partnerId`, secret key, and other registration details, then try again.
`InvalidPartnerDetails`	You provided incorrect details during sign-in.	Verify your credentials (`partnerId`, `partnerToken`, etc.) are correct before attempting to sign in again.
`ServiceError`	An unexpected error occurred on the Suki server.	This is usually a temporary issue. Retry the API call after a short delay. If the problem persists, contact support.
`UserNotFound`	The user you are trying to access does not exist.	Ensure the user is registered before trying to sign in. Tip: Enable auto-onboarding by setting autoRegister: `true` in the useAuth hook.

Session lifecycle errors

These errors occur when you attempt to start, pause, resume, cancel, or submit an ambient session.

Starting a session (StartSessionFailed)

Error code	Cause	Solution
`InvalidSessionState`	The session is already finalized.	Create a new session. You cannot modify a session once it is finalized.
`InvalidSessionState`	The session is already in a recording state.	This likely indicates a bug in your logic. If you intended to restart, pause the session first.
`NetworkOffline`	The device does not have an active internet connection.	Ensure there is an active internet connection and try starting the session again.
`StreamError`	Failed to establish a stream with the Suki backend.	This is likely a temporary issue. Retry starting the session. If the problem persists, contact support.
`AudioRecorderFailure`	Failed to access or start the microphone.	This is likely a browser or permission issue. Check your microphone settings and permissions, then retry.

Pausing a session (PauseSessionFailed)

Error code	Cause	Solution
`InvalidSessionState`	The session is already finalized.	Create a new session. You cannot modify a session once it is finalized.
`InvalidSessionState`	The session is not in a recording state.	This likely indicates a bug in your logic; you cannot pause a session that isn’t recording.
`StreamError`	Failed to close the stream with the backend.	This is likely a temporary issue. No action is usually needed.

Resuming a session (ResumeSessionFailed)

Error code	Cause	Solution
`InvalidSessionState`	The session is already finalized.	Create a new session. You cannot modify a session once it is finalized.
`InvalidSessionState`	The session is not in a paused state.	This likely indicates a bug in your logic; you cannot resume a session that isn’t paused.
`StreamError`	Failed to resume the stream with the backend.	This is likely a temporary issue. No action is usually needed.
`AudioRecorderFailure`	Failed to start the microphone.	This is likely a browser issue. Check microphone settings and permissions, then retry.

Canceling a session (CancelSessionFailed)

Error code	Cause	Solution
`InvalidSessionState`	The session is already finalized.	Create a new session. You cannot modify a session once it is finalized.
`StreamError`	Failed to close the stream with the backend.	This is likely a temporary issue. Retry cancelling the session.

Submitting a session (SubmitSessionFailed)

Error code	Cause	Solution
`StreamError`	Failed to close the stream with the backend.	This is likely a temporary issue. Retry submitting the session.
`ServiceError`	Unable to update the session state to “ready” for note generation.	This is likely a temporary issue. Retry submitting the session.
`OfflineSaveFailed`	Failed to store the offline session in browser storage (IndexedDB).	Your browser storage may be full. Clear your cache or IndexedDB. If the SDK is closed at this stage without saving, the session data will be lost.

Interoperability errors

These errors occur when you create an interoperable ambient session, clear a remote blocking session, or list notes for an EMR encounter.

Session already exists (`sessionAlreadyExists`)

session.create() fails with this reason when another Suki product already has an active ambient session for the same provider and EMR encounter. The HTTP status is 409.

Error reason	Cause	Solution
`sessionAlreadyExists`	Another Suki product already has an active ambient session for the same provider and EMR encounter.	Read `blockingSessionId` from `error.additionalProperties`. Call `cancelRemote` or `endRemote`, then retry `session.create()` with the same `emrEncounterId` and `encounterId`.

additionalProperties?: {
  blockingSessionId: string;
  blockingModality?: string;
  elapsed?: string;
};

Some JSDoc comments refer to metadata.blockingSessionId. The runtime field is additionalProperties. Refer to Handle ambient session conflicts.

Cancel or end remote session failed

These errors occur when cancelRemote or endRemote fails while you clear a blocking remote session.

Error reason	Cause	Solution
`cancelRemoteSessionFailed`	The request to cancel the remote blocking session failed.	Retry `cancelRemote` with the same `blockingSessionId`, then retry create.
`endRemoteSessionFailed`	The request to end the remote blocking session failed.	Retry `endRemote` with the same `blockingSessionId`, then retry create.

Get encounter info failed (`getEncounterInfoFailed`)

This error occurs when useGetEncounterInfo or PlatformClient.getEncounterInfo cannot list notes for an EMR encounter.

Error reason	Cause	Solution
`getEncounterInfoFailed`	`emrEncounterId` was empty, or the encounter info request failed.	Pass a non-empty EMR encounter id (UUID or non-UUID, at most 36 characters) and retry `useGetEncounterInfo` or `PlatformClient.getEncounterInfo`.

Context update errors (ContextUpdateFailed)

These errors occur when you call setSessionContext to update patient information or visit metadata during an active session.

Error code	Cause	Solution
`InvalidSessionState`	The session is already finalized.	Create a new session. You cannot modify the context of a session once it is finalized.
`ServiceError`	Failed to update the context on the server.	Retry updating the session context.

Next steps

Refer to the Offline mode guide to learn more about how to handle offline mode in the Suki Headless Web SDK. Refer to Handle ambient session conflicts for remote conflict recovery and remote session end handling.

Get Started

Concepts & Feature Guides

API Reference

Resources

Error Handling

Authentication Errors

Session Lifecycle Errors

Interoperability Errors

Pausing Session

Resuming Session

Cancelling Session

Submitting Session

Context Update Errors

Authentication errors (AuthError)

Session lifecycle errors

Starting a session (StartSessionFailed)

Pausing a session (PauseSessionFailed)

Resuming a session (ResumeSessionFailed)

Canceling a session (CancelSessionFailed)

Submitting a session (SubmitSessionFailed)

Interoperability errors

Session already exists (`sessionAlreadyExists`)

Cancel or end remote session failed

Get encounter info failed (`getEncounterInfoFailed`)

Context update errors (ContextUpdateFailed)

Next steps

Authentication Errors

Session Lifecycle Errors

Interoperability Errors

Pausing Session

Resuming Session

Cancelling Session

Submitting Session

Context Update Errors

​Authentication errors (AuthError)

​Session lifecycle errors

​Starting a session (StartSessionFailed)

​Pausing a session (PauseSessionFailed)

​Resuming a session (ResumeSessionFailed)

​Canceling a session (CancelSessionFailed)

​Submitting a session (SubmitSessionFailed)

​Interoperability errors

​Session already exists (sessionAlreadyExists)

​Cancel or end remote session failed

​Get encounter info failed (getEncounterInfoFailed)

​Context update errors (ContextUpdateFailed)

​Next steps

Authentication errors (AuthError)

Session lifecycle errors

Starting a session (StartSessionFailed)

Pausing a session (PauseSessionFailed)

Resuming a session (ResumeSessionFailed)

Canceling a session (CancelSessionFailed)

Submitting a session (SubmitSessionFailed)

Interoperability errors

Session already exists (`sessionAlreadyExists`)

Cancel or end remote session failed

Get encounter info failed (`getEncounterInfoFailed`)

Context update errors (ContextUpdateFailed)

Next steps