Skip to main content
session.create() fails with reason sessionAlreadyExists (HTTP 409) when another Suki product already has an active ambient session for the same provider and EMR encounter. This applies to Ambient interoperability in the Headless Web SDK. Dictation and Form filling do not support interoperability.
Use @suki-sdk/platform and @suki-sdk/platform-react v0.3.0 or later. Pass emrEncounterId on create so the note is interoperable.

Common causes

  • A clinician started ambient on Web SDK, Mobile SDK, or another client for the same emrEncounterId.
  • A previous session was left open instead of ended or canceled.
  • Your UI retries create without clearing the remote session first.

Fix

1

Catch sessionAlreadyExists

When session.create() fails, check whether reason === "sessionAlreadyExists". The HTTP status is 409.
2

Read blockingSessionId

Read blockingSessionId from error.additionalProperties. Some JSDoc comments say metadata. The runtime field is additionalProperties.
3

Clear the Remote Session

Call cancelRemote to discard the blocking session without generating a note, or endRemote so any audio already captured can be processed. Pass { ambientSessionId: blockingSessionId } on useAmbient or useAmbientSession.
4

Retry Create

After the remote call succeeds, retry session.create() with the same emrEncounterId and encounterId. Headless Web SDK does not require a delay between a successful remote clear and the retry.
The sessionAlreadyExists conflict applies only when session.create() runs online. If the first ambient session is fully offline, another Suki product can start a session for the same EMR encounter without receiving a conflict error.
React
Use cancelRemote when you want to discard the blocking session. Use endRemote when you want the blocking session to end and process any audio already captured. If cancelRemote fails, the error reason is cancelRemoteSessionFailed. If endRemote fails, the error reason is endRemoteSessionFailed.

Mobile SDK

On Mobile SDK, a similar interop conflict is remoteSessionConflict(blockingSessionId:): another client holds an active session for the encounter. Use blockingSessionId with cancelRemoteAmbientSession or endSessionRemotely, then retry create. See Mobile SDK error messages and Create ambient session.

Next steps

Resolve a remote session conflict - End the remote session, then retry create session_in_progress on Partner API create - HTTP 409 concurrent create on Partner APIs Create ambient session - useAmbient, including cancelRemote and endRemote Manage ambient session - onSessionTerminatedByPeer when another product ends the live session Empty notes after end session - Poll status before retrieving content
Last modified on September 29, 2026