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

The SDK returns typed errors that you can inspect with `errors.As`.

## Error types

The Go SDK exports:

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

## Catch typed errors

```go theme={null}
import (
  "context"
  "errors"
  "fmt"

  mailglyph "github.com/MailGlyph/mailglyph-go"
)

client := mailglyph.New("sk_your_secret_key")

_, err := client.Contacts.Get(context.Background(), "missing-contact-id")
if err != nil {
  var notFoundErr *mailglyph.NotFoundError
  var validationErr *mailglyph.ValidationError
  var authErr *mailglyph.AuthenticationError
  var rateLimitErr *mailglyph.RateLimitError
  var apiErr *mailglyph.ApiError
  var baseErr *mailglyph.MailGlyphError

  switch {
  case errors.As(err, &notFoundErr):
    fmt.Println("Contact not found")
  case errors.As(err, &validationErr):
    fmt.Println("Validation failed", validationErr.Message)
  case errors.As(err, &authErr):
    fmt.Println("Check API key type or value")
  case errors.As(err, &rateLimitErr):
    fmt.Println("Rate limited, retry after seconds:", rateLimitErr.RetryAfterSeconds)
  case errors.As(err, &apiErr):
    fmt.Println("Server/API error", apiErr.StatusCode, apiErr.Message)
  case errors.As(err, &baseErr):
    fmt.Println("MailGlyph SDK error", baseErr.StatusCode, baseErr.Type)
  default:
    panic(err)
  }
}
```

## Key-type mismatch example

`Events.Track` requires a **public** key and most other methods require a **secret** key.

```go theme={null}
import (
  "context"
  "errors"
  "fmt"

  mailglyph "github.com/MailGlyph/mailglyph-go"
)

secretClient := mailglyph.New("sk_your_secret_key")

_, err := secretClient.Events.Track(context.Background(), &mailglyph.TrackEventParams{
  Email: "user@example.com",
  Event: "signup",
})
if err != nil {
  var authErr *mailglyph.AuthenticationError
  if errors.As(err, &authErr) {
    fmt.Println(authErr.Message)
  }
}
```

## Retry and timeout behavior

The Go SDK automatically retries transient API responses:

* Up to 3 retries for `429` and `5xx` responses
* Uses `Retry-After` when present (`seconds` or HTTP date)
* Falls back to exponential backoff with jitter when `Retry-After` is missing or invalid

The Go SDK does **not** retry transport-level request failures.

Timeout behavior:

* `mailglyph.WithTimeout(...)` sets the underlying `http.Client` timeout
* Context cancellation and context deadlines stop retries and return immediately

```go theme={null}
import (
  "context"
  "errors"
  "time"

  mailglyph "github.com/MailGlyph/mailglyph-go"
)

client := mailglyph.New("sk_your_secret_key", mailglyph.WithTimeout(10*time.Second))
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

_, err := client.Emails.Verify(ctx, "user@example.com")
if err != nil {
  if errors.Is(err, context.DeadlineExceeded) {
    // Request timed out.
  }
}
```


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