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:August 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

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.

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.

Get Started

Concepts & Feature Guides

API Reference

Resources

Error Handling

Authentication Errors

Session Lifecycle 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)

Context update errors (ContextUpdateFailed)

Next steps

Authentication Errors

Session Lifecycle 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)

​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)

Context update errors (ContextUpdateFailed)

Next steps