> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling In Web SDK

> Learn how to handle errors and exceptions in the Web SDK

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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.

    <br />

    <br />

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

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">June 2026</span>
  </div>
</div>

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.

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
      const unsubscribeError = sdkClient.on(
        "error",
        (error) => {
          console.error("SDK error occurred:", error);
          // Use error.code, error.details.name, and error.details.reason
        },
      );
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}

      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);
            // Use error.code, error.details.name, and error.details.reason
          });

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

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

  ```
</View>

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

```ts SukiError.ts theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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 JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "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](/web-sdk/api-reference/types/suki-error#errorcode-identifier) section in the types reference.

## Handling specific errors

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

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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);
    }
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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]);
  ```
</View>

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

<Icon icon="file-lines" iconType="solid" /> Refer to the [Token refresh](/web-sdk/guides/token-refresh) guide to learn more about how to refresh the token and keep the session alive.