Errors - MailGlyph Docs

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

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.

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: "[email protected]",
  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

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, "[email protected]")
if err != nil {
  if errors.Is(err, context.DeadlineExceeded) {
    // Request timed out.
  }
}