> For the complete documentation index, see [llms.txt](https://emeditweb.gitbook.io/pulsar-stellar-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://emeditweb.gitbook.io/pulsar-stellar-sdk/sdk-reference/errors.md).

# Errors

Every SDK method throws from one hierarchy. Three rules hold across all of it: nothing throws a bare `Error`, so you branch with `instanceof`; every error carries the `operation` it came from; and wrapping preserves the original as `cause`. Absence is always `null`, never `undefined`.

For when the SDK returns `null` versus throws, see [Error handling](/pulsar-stellar-sdk/concepts/error-handling.md).

## `PulsarError`

```ts
abstract class PulsarError extends Error {
  readonly operation: string;
  readonly details: Readonly<Record<string, unknown>>;
  override toString(): string;
}
```

The base class for every SDK error. **Abstract: catch it to handle every SDK failure at once, but never construct it.** You always receive one of the two concrete subclasses below.

* **`operation`**: the SDK operation that failed, such as `client.events` or `rpc.fetchLiveEvents`.
* **`details`**: identifiers worth having in a log line, frozen so a handler cannot edit them.
* **`toString()`**: renders name, message, operation, and details on one line, because `Error.prototype.toString` drops exactly the context a production log needs.

```ts
import { PulsarError } from '@pulsar-stellar/sdk';

catch (error) {
  if (error instanceof PulsarError) {
    console.error(error.toString()); // includes operation and details
  }
}
```

The option types `PulsarErrorOptions` and `PulsarNetworkErrorOptions` are exported for constructing subclasses in your own extensions; ordinary consumers do not need them.

## `PulsarNetworkError`

```ts
class PulsarNetworkError extends PulsarError {
  readonly status: number | null;
  readonly url: string | null;
}
```

A request did not produce a usable response: an unreachable indexer or RPC endpoint, a timeout, a non-success HTTP status, or a body that could not be read. It does **not** cover a response that arrived intact but failed validation; that is a `PulsarValidationError`.

* **`status`**: the HTTP status, or `null` when the request never produced one (a timeout or DNS failure before any response).
* **`url`**: the URL called, or `null` when the failure preceded the request.

```ts
import { PulsarNetworkError } from '@pulsar-stellar/sdk';

catch (error) {
  if (error instanceof PulsarNetworkError) {
    console.error('request failed', error.status, error.url, error.operation);
  }
}
```

## `PulsarValidationError`

```ts
class PulsarValidationError extends PulsarError {
  readonly issues: readonly ZodIssue[];
  static fromZodError(error: ZodError, options: Omit<PulsarErrorOptions, 'cause'>): PulsarValidationError;
}
```

A value did not match its schema. Thrown for caller input the SDK rejects, and for a server response that does not match the shape this SDK version expects. The `operation` field tells you which of the two it was.

* **`issues`**: every issue Zod reported, in order, so you can point at the offending field rather than the whole message.
* **`fromZodError(error, options)`**: wraps a `ZodError`, naming the first offending path in the message and keeping the original as `cause`.

```ts
import { PulsarValidationError } from '@pulsar-stellar/sdk';

catch (error) {
  if (error instanceof PulsarValidationError) {
    for (const issue of error.issues) {
      console.error(issue.path.join('.'), issue.message);
    }
  }
}
```

## `findPulsarError(error)`

```ts
findPulsarError(error: unknown): PulsarError | null
```

Finds the first Pulsar error in a `cause` chain. Useful when your own code has wrapped an SDK error and you need the original context back. Returns `null` when the chain holds none, never `undefined`, so you branch on `=== null` without a second check. The walk is cycle-safe: a self-referential chain terminates rather than looping.

```ts
import { findPulsarError } from '@pulsar-stellar/sdk';

catch (error) {
  const pulsar = findPulsarError(error);
  if (pulsar !== null) console.error(pulsar.operation, pulsar.details);
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://emeditweb.gitbook.io/pulsar-stellar-sdk/sdk-reference/errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.