Skip to main content

​
Overview

The Suki SDK provides a structured and consistent error handling system to help you gracefully manage errors such as initialization failures, patient creation issues, and note submission problems. All errors emitted by the SDK follow a consistent structure with error codes, names, and optional reasons to help you debug efficiently.

​
Listening For Errors

You can 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.
  • JavaScript
  • React
JavaScript
const unsubscribeError = sdkClient.on(
  "error",
  (error) => {
    console.error("SDK error occurred:", error);
    // You can use error.code, error.details.name, and error.details.reason
  },
);

​
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 error codes section in the types reference.

​
Handling Specific Errors

Use switch statements or conditional logic to handle specific error codes:
  • JavaScript
  • React
JavaScript
const unsubscribeError = sdkClient.on("error", (error) => {
  switch (error.code) {
    case "SUKI0002":
      console.error("Authentication failed. Please log in again.");
      break;
    case "SUKI0009":
      console.error("Patient creation failed. Check input data.");
      break;
    case "SUKI0013":
      if (error.details.reason === "no-ambient") {
        console.error("Ambient session was not found.");
      }
      break;
    default:
      console.error("Unhandled SDK error:", error.details.message);
  }
});

​
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 Token Refresh guide to learn more about how to refresh the token and keep the session alive.