Error Handling In Web SDK

Quick summary

The SDK uses a consistent error structure with error codes, names, and optional reasons to help you handle errors like initialization failures, patient creation issues, and note submission problems.

Listen for SDK-wide errors by subscribing to the error event using either the SukiClient instance (JavaScript) or the useSuki hook (React). This allows you to log and respond to issues across authentication, session management, or note handling.

Last updated:June 2026

The SDK uses a consistent error structure to help you handle errors like initialization failures, patient creation issues, and note submission problems. All SDK errors include an error code, name, and optional reason to make debugging easier.

Listening for errors

Listen for SDK-wide errors by subscribing to the error event using either the SukiClient instance (JavaScript) or the useSuki hook (React). This allows you to log and respond to issues across authentication, session management, or note handling.

Error object structure

Every error emitted by the SDK conforms to a predictable shape that includes a top-level code and a details object with contextual information.

SukiError.ts

type SukiError = {
  code: "SUKI0001" | "SUKI0002" | ...;
  details: {
    name: string; // e.g., "init:sdk-init-failed"
    message: string;
    reason?: string; // e.g., "lib-error", "no-init"
  };
};

Example

JSON

{
  "code": "SUKI0001",
  "details": {
    "name": "init:sdk-init-failed",
    "message": "SDK initialization failed",
    "reason": "lib-error"
  }
}

For more details on the error codes and their meanings, refer to the error codes section in the types reference.

Handling specific errors

Use switch statements or conditional logic to handle specific error codes:

Best practices

Log or report the full SukiError object for debugging and support.
Use reason field for granular handling or user messaging.
Always show helpful, user-friendly messages when relevant.
Implement retries for transient errors (e.g., token expiration or network interruptions) to ensure resilience.

Next steps

Refer to the Token refresh guide to learn more about how to refresh the token and keep the session alive.

​Listening for errors

​Error object structure

​Example

​Handling specific errors

​Best practices

​Next steps