> ## Documentation Index > Fetch the complete documentation index at: https://developer.suki.ai/llms.txt > Use this file to discover all available pages before exploring further. # Handle Ambient Session Conflicts > Clear a blocking remote ambient session with cancelRemote or endRemote, then retry create, and keep UI in sync when another Suki product ends the live session
Clear a blocking remote ambient session with `cancelRemote` or `endRemote` when create fails with `sessionAlreadyExists`, then retry create. Keep your UI in sync with `onSessionTerminatedByPeer` when another Suki product cancels or ends the live session.
* These flows apply only to **Ambient interoperability for 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. Refer to [Ambient interoperability](/headless-web-sdk/guides/ambient-interoperability). Only **one active ambient session** can exist for the same **provider and EMR encounter** across Suki products. * If `session.create()` fails because another Suki product already has an active session for the same provider and EMR encounter, clear the existing session with `cancelRemote` or `endRemote`, then retry the create request. * If another Suki product cancels or ends the session currently active in your Headless Web SDK app, the SDK clears its local session state and calls `onSessionTerminatedByPeer`. ## Resolve an active session conflict When another Suki product already has an active ambient session for the same provider and EMR encounter, `session.create()` fails with: * **HTTP status:** `409` * **`reason`:** `sessionAlreadyExists` * **`blockingSessionId`:** The ID of the active session blocking the create request, returned in `error.additionalProperties` To resolve the conflict: 1. Catch the `session.create()` error and check whether `reason === "sessionAlreadyExists"`. 2. Read the `blockingSessionId` from `error.additionalProperties`. 3. Call **`cancelRemote`** or **`endRemote`** for the blocking session. 4. After the remote operation succeeds, retry `session.create()` with the same `emrEncounterId` and `encounterId`. The Headless Web SDK does not require a delay between a successful `cancelRemote` or `endRemote` call and the retry of `session.create()`. 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. ### Conflict error fields When create fails with a remote session conflict, the thrown `PlatformError` includes the following fields. Identifies a remote session conflict. Check this value before calling `cancelRemote` or `endRemote`. Human-readable conflict message from the platform. Use this for UI copy when present. Structured conflict details. Some JSDoc comments refer to `metadata`. The runtime field is `additionalProperties`. Ambient session id of the blocking remote session. Maps to Ambient API `ambient_session_id`. Pass this value to `cancelRemote` or `endRemote`. **Optional**: Modality that owns the blocking session, for example `"WEB_SDK"` or `"MOBILE"`. **Optional**: How long the blocking session has been active, for example `"0s"` or `"5m"`. ### Remote recovery actions `cancelRemote` and `endRemote` are available on **`useAmbient`** and **`useAmbientSession`**. Pass the blocking session id from the conflict error. Do not pass your local `ambientSessionId` unless that id is the blocking session. Discards the blocking remote session without generating a note from that session. Pass `{ ambientSessionId: blockingSessionId }`. Ends the blocking remote session so any audio already captured can be processed. Pass `{ ambientSessionId: blockingSessionId }`. If `cancelRemote` fails, the error reason is **`cancelRemoteSessionFailed`**. If `endRemote` fails, the error reason is **`endRemoteSessionFailed`**. Refer to [Error handling](/headless-web-sdk/guides/error-handling#interoperability-errors). ### Code example for clearing a remote session conflict ```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { useAmbient } from "@suki-sdk/platform-react"; export function CreateOrResolveConflict() { const { cancelRemote, endRemote, session } = useAmbient(); // Reuse the same encounterId for every re-ambient session on this note. const existingEncounterId = "visit-note-1"; const emrEncounterId = "6ec3920f-b0b1-499d-a4e9-889bf788e5ab"; const createOrResolveConflict = async () => { try { await session.create({ encounterId: existingEncounterId, emrEncounterId, }); } catch (error) { if ( error && typeof error === "object" && "reason" in error && error.reason === "sessionAlreadyExists" ) { const blockingSessionId = "additionalProperties" in error && error.additionalProperties && typeof error.additionalProperties === "object" && "blockingSessionId" in error.additionalProperties ? String(error.additionalProperties.blockingSessionId) : undefined; if (!blockingSessionId) { throw error; } // Discard the blocking session: await cancelRemote({ ambientSessionId: blockingSessionId }); // Or end the blocking session so captured audio can be processed: // await endRemote({ ambientSessionId: blockingSessionId }); await session.create({ encounterId: existingEncounterId, emrEncounterId, }); return; } throw error; } }; return ( ); } ``` * 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. ## What happens when another Suki product ends the live session If another Suki product cancels or ends the ambient session that is currently active in your Headless Web SDK app, the SDK clears local session state before it notifies your app. The SDK: * Stops the microphone. * Deletes local audio and IndexedDB metadata for the session. * Resets the stream. * Sets local status to **`submitted`** when the termination reason is **`ENDED`**, or to **`cancelled`** otherwise. Then it calls **`onSessionTerminatedByPeer`** with `{ sessionId, reason }`. In that callback, update your recording UI to match the new session status. The Headless Web SDK already stopped the microphone and cleared local session state, so do not call `cancel()`, `submit()`, `cancelRemote()`, or `endRemote()`. ### Remote session end callback Pass **`onSessionTerminatedByPeer`** to `useAmbientSession` when you need to keep recording UI in sync after another Suki product cancels or ends the live session. **Optional**: Called after another Suki product cancels or ends the live session. Update your recording UI to match the new session status. Do not call `cancel()`, `submit()`, `cancelRemote()`, or `endRemote()`. The SDK already cleared local mic, stream, and session state. The ambient session id that was cancelled or ended remotely. Termination reason from the other product, for example `"ENDED"` or `"CANCELLED"`. When the reason is `"ENDED"`, local status becomes `submitted`. Otherwise local status becomes `cancelled`. ### Code example for handling a remote session end ```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { useAmbientSession } from "@suki-sdk/platform-react"; export function RemoteSessionEndListener({ ambientSessionId, }: { ambientSessionId: string; }) { useAmbientSession({ ambientSessionId, onSessionTerminatedByPeer: ({ sessionId, reason }) => { // reason: "ENDED" | "CANCELLED" | ... // Update recording UI. Do not call cancel, submit, cancelRemote, or endRemote. console.log("Remote session ended", sessionId, reason); }, }); return null; } ``` ## Available cookbooks