Error Handling

Learn how to handle errors and exceptions in the 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.

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.

Last updated:December 2025

Overview

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

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

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
  },
);

React

React

import { useSuki } from "@suki-sdk/react";
import { useEffect } from "react";

const MyComponent = () => {
  const { on } = useSuki();

  useEffect(() => {
    const unsubscribe = on("error", (error) => {
      console.error("SDK error occurred:", error);
      // You can use error.code, error.details.name, and error.details.reason
    });

    return () => {
      unsubscribe();
    };
  }, [on]);

  return <div>App Content</div>;
};

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

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);
  }
});

React

React

useEffect(() => {
  const unsubscribe = 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);
    }
  });

  return () => unsubscribe();
}, [on]);

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.