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. 
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

{
  "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, see the Error Codes and Descriptions section below.

​
Handling Specific Errors

Use switch statements or conditional logic to handle specific error codes: 
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.