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

# Errors

> Handle typed MailGlyph SDK errors in Node.js applications.

The SDK throws typed errors that you can catch and handle.

## Error classes

The Node.js SDK exports:

* `MailGlyphError`
* `AuthenticationError`
* `ValidationError`
* `NotFoundError`
* `RateLimitError`
* `ApiError`

## Catch typed errors

```ts theme={null}
import MailGlyph, {
  ApiError,
  AuthenticationError,
  MailGlyphError,
  NotFoundError,
  RateLimitError,
  ValidationError
} from 'mailglyph';

const client = new MailGlyph(process.env.MAILGLYPH_SECRET_KEY as string);

try {
  await client.contacts.get('missing-contact-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Contact not found');
    return;
  }

  if (error instanceof ValidationError) {
    console.error('Validation failed', error.details);
    return;
  }

  if (error instanceof AuthenticationError) {
    console.error('Check API key type or value');
    return;
  }

  if (error instanceof RateLimitError) {
    console.error('Rate limited, retry after seconds:', error.retryAfter);
    return;
  }

  if (error instanceof ApiError) {
    console.error('Server/API error', error.status, error.details);
    return;
  }

  if (error instanceof MailGlyphError) {
    console.error('MailGlyph SDK error', error.status, error.message);
    return;
  }

  throw error;
}
```

## Key-type mismatch example

`events.track` requires a **public** key and most other methods require a **secret** key.

```ts theme={null}
const secretClient = new MailGlyph(process.env.MAILGLYPH_SECRET_KEY as string);

try {
  await secretClient.events.track({
    email: 'user@example.com',
    event: 'signup'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error(error.message);
  }
}
```

## Retry and timeout behavior

The SDK automatically retries transient failures:

* Up to 3 retries for `429` and `5xx` responses
* Uses exponential backoff when `retry-after` is not present
* Throws timeout errors when request duration exceeds the configured timeout

You can customize timeout in client config:

```ts theme={null}
const clientWithShortTimeout = new MailGlyph(process.env.MAILGLYPH_SECRET_KEY as string, {
  timeout: 10_000
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.