> ## 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 exceptions in PHP applications.

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

## Exception classes

The PHP SDK exports:

* `MailGlyphException`
* `AuthenticationException`
* `ValidationException`
* `NotFoundException`
* `RateLimitException`
* `ApiException`

## Catch typed exceptions

```php theme={null}
<?php

use MailGlyph\Exceptions\ApiException;
use MailGlyph\Exceptions\AuthenticationException;
use MailGlyph\Exceptions\MailGlyphException;
use MailGlyph\Exceptions\NotFoundException;
use MailGlyph\Exceptions\RateLimitException;
use MailGlyph\Exceptions\ValidationException;
use MailGlyph\MailGlyph;

$client = new MailGlyph($_ENV['MAILGLYPH_SECRET_KEY']);

try {
    $client->contacts->get('missing-contact-id');
} catch (NotFoundException $error) {
    error_log('Contact not found');
} catch (ValidationException $error) {
    error_log('Validation failed: ' . $error->getMessage());
    error_log(json_encode($error->getErrorData()) ?: '{}');
} catch (AuthenticationException $error) {
    error_log('Check API key type or value');
} catch (RateLimitException $error) {
    error_log('Rate limited: ' . $error->getMessage());
} catch (ApiException $error) {
    error_log('Server/API error: ' . (string) $error->getStatusCode());
} catch (MailGlyphException $error) {
    error_log('MailGlyph SDK error: ' . $error->getMessage());
}
```

## Key-type mismatch example

`events->track()` requires a **public** key and most other methods require a **secret** key.

```php theme={null}
<?php

use MailGlyph\Exceptions\AuthenticationException;
use MailGlyph\MailGlyph;

$secretClient = new MailGlyph($_ENV['MAILGLYPH_SECRET_KEY']);

try {
    $secretClient->events->track([
        'email' => 'user@example.com',
        'event' => 'signup',
    ]);
} catch (AuthenticationException $error) {
    error_log($error->getMessage());
}
```

## Retry and timeout behavior

The PHP SDK automatically retries transient failures:

* Up to `maxRetries` retries (default `3`)
* Retries `429` and `5xx` responses
* Retries transport-level HTTP client failures
* Uses `Retry-After` when present, otherwise exponential backoff with jitter

Timeout is configured in milliseconds with the `timeout` client option.

```php theme={null}
<?php

use MailGlyph\MailGlyph;

$client = new MailGlyph($_ENV['MAILGLYPH_SECRET_KEY'], [
    'timeout' => 10_000,
    'maxRetries' => 1,
]);
```

The PHP SDK does not expose a `retryAfter` property on exceptions. Use the exception type, message, `getStatusCode()`, and `getErrorData()` for handling logic.


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