Skip to main content
The SDK raises typed exceptions that you can catch and handle.

​
Error classes

The Python SDK exports:
  • MailGlyphError
  • AuthenticationError
  • ValidationError
  • NotFoundError
  • RateLimitError
  • ApiError

​
Catch typed errors

from mailglyph import MailGlyph
from mailglyph.exceptions import (
    ApiError,
    AuthenticationError,
    MailGlyphError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

client = MailGlyph("sk_your_secret_key")

try:
    client.contacts.get("missing-contact-id")
except NotFoundError:
    print("Contact not found")
except ValidationError as error:
    print("Validation failed", error.payload)
except AuthenticationError:
    print("Check API key type or value")
except RateLimitError as error:
    print("Rate limited, retry after seconds:", error.retry_after)
except ApiError as error:
    print("Server/API error", error.status_code, error.payload)
except MailGlyphError as error:
    print("MailGlyph SDK error", error.status_code, error.message)

​
Key-type mismatch example

events.track requires a public key and most other methods require a secret key. 
from mailglyph import MailGlyph
from mailglyph.exceptions import AuthenticationError

secret_client = MailGlyph("sk_your_secret_key")

try:
    secret_client.events.track(email="[email protected]", event="signup")
except AuthenticationError as error:
    print(error.message)

​
Retry and timeout behavior

The SDK automatically retries transient failures:
  • Up to max_retries retries (default 3)
  • Retries 429 and 5xx responses
  • Retries transport-level failures (including timeouts)
  • Uses Retry-After when present, otherwise exponential backoff with jitter
If retries are exhausted, the SDK raises ApiError.

​
Configure timeout and retries

from mailglyph import MailGlyph

client = MailGlyph(
    "sk_your_secret_key",
    timeout=10.0,
    max_retries=1,
)

​
Async error handling

The async client raises the same exception types: 
from mailglyph import AsyncMailGlyph
from mailglyph.exceptions import MailGlyphError


async def run() -> None:
    try:
        async with AsyncMailGlyph("sk_your_secret_key") as client:
            await client.contacts.get("missing-contact-id")
    except MailGlyphError as error:
        print(error.status_code, error.message)