Error Handling

Handle authentication, session lifecycle, Embedded Forms context, and structured data errors in the Headless Web SDK

This guide details the error codes exposed by the Suki Headless SDK. Use search or the category filter to find the error you need to handle.

Categories

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.

Starting a session (StartSessionFailed)

These errors occur when you start an ambient session.

When the microphone cannot start, including when the deviceId you passed is missing or disconnected, use the AudioRecorderFailure row below or under Resuming a session.

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, including when an exact deviceId is unavailable.	This is likely a browser or permission issue, or the requested deviceId is missing or disconnected. Check microphone settings and permissions. If you passed an exact deviceId, refresh your device list, ask the user to pick another mic, then retry. The SDK does not fall back to the browser default when an exact device is missing. On Platform Client, inspect code: "StartSessionFailed" and reason: "AudioRecorderFailure" (plus cause for the underlying getUserMedia error). In React useAmbientSession, start often rethrows a string from error.toString() that includes those Code and Reason values.

Pausing a session (PauseSessionFailed)

These errors occur when you pause an ambient session.

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)

These errors occur when you resume an ambient session.

When the microphone cannot start, including when the deviceId you passed is missing or disconnected, use the AudioRecorderFailure row below or under Starting a session.

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, including when an exact deviceId is unavailable.	This is likely a browser or permission issue, or the requested deviceId is missing or disconnected. Check microphone settings and permissions. If you passed an exact deviceId, refresh your device list, ask the user to pick another mic, then retry. The SDK does not fall back to the browser default when an exact device is missing. On Platform Client, inspect code: "ResumeSessionFailed" and reason: "AudioRecorderFailure" (plus cause for the underlying getUserMedia error). In React useAmbientSession, resume often rethrows a string from error.toString() that includes those Code and Reason values.

Canceling a session (CancelSessionFailed)

These errors occur when you cancel an ambient session.

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)

These errors occur when you submit an ambient session.

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.

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.

setSessionContext (ContextUpdateFailed)

Call setSessionContext after you create the session and before you submit. The session must still be in the created state. This includes Embedded Form seeds and prior section text. PlatformClient.setSessionContext throws AmbientSessionError with code: "ContextUpdateFailed".

Error code	Cause	Solution
InvalidSessionState	The session is no longer in the created state (for example after submit or cancel).	Seed Embedded Forms and other context after create and before submit. Create a new session if this one is already finalized.
ServiceError	The request failed, or IndexedDB could not store the context.	Retry setSessionContext. If IndexedDB is full, clear browser storage, then retry.

In React, setSessionContext from useAmbientSession often throws the error as a string from error.toString(), which includes the Code and Reason values. Prefer inspecting that string, or call PlatformClient.setSessionContext when you need the full error object.

updateSessionContext (updateSessionContextFailed)

Use updateSessionContext (or useUpdateAmbientSessionContext) for mid-visit Embedded Form changes. Pass ambientSessionId and updateMask (prefer ["sections"]), then send the full sections list you want. This call throws PlatformError with reason: "updateSessionContextFailed", not AmbientSessionError.

Error reason	Cause	Solution
updateSessionContextFailed	ambientSessionId or updateMask is missing, or the request fails.	Pass both ambientSessionId and updateMask, then retry. Prefer useUpdateAmbientSessionContext in React. Nested paths under sections, such as sections.precharted_content, are not supported.

A successful updateSessionContext still reaches Suki even when IndexedDB has no prior context row. The SDK skips the IndexedDB mirror and logs a warning. Call setSessionContext first when you need offline upload to include Embedded Forms. Refer to Offline behavior.

Structured data and content errors

These errors occur when session, encounter, or note helpers cannot read structured data or note content. Embedded Form fills come from section_structured_values on the session or encounter helpers.

Error reason	Cause	Solution
getStructuredDataFailed	The session, encounter, or note id is empty, or the structured data request fails.	Pass a non-empty id and retry getAmbientSessionStructuredData, getAmbientEncounterStructuredData, getAmbientNoteStructuredData, or the matching React hooks.
getSectionStructuredDataFailed	The session or encounter id is empty, or the Embedded Forms request fails.	Pass a non-empty id and retry getAmbientSessionSectionStructuredData, getAmbientEncounterSectionStructuredData, or the matching React hooks.
getContentFailed	The session, encounter, or note id is empty, or the content request fails.	Pass a non-empty id and retry the content helper or hook.

useUpdateAmbientSessionContext and the read hooks return the PlatformError object. Note structured data does not include Embedded Forms in this release. Read Embedded Forms from the session or encounter helpers. Refer to Seed and read Embedded Forms.

Next steps

Seed and read Embedded Forms - Seed, update, and read Embedded Forms, including the errors above.

Offline mode - Track sessions that upload after the network returns.

Handle ambient session conflicts - Remote conflict recovery and remote session end handling.