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.
Overview
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.
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 partner ID, secret key, and other registration details, then try again. |
InvalidPartnerDetails | You provided incorrect details during sign-in. | Verify your credentials (partner ID, partner token, 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: You can 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. Warning: 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.
