Errors

Error Response Format

All errors return a consistent JSON structure with an HTTP status code:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": {
      "field": "from",
      "reason": "not a valid email"
    }
  }
}

Field	Type	Description
`code`	string	Machine-readable error code
`message`	string	Human-readable description
`details`	object \| null	Optional context (e.g., validation errors)

Status Codes

Status	Code	Description
`400`	`VALIDATION_ERROR`	Request body failed validation
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`INSUFFICIENT_SCOPE`	API key lacks the required scope
`404`	`NOT_FOUND`	Resource does not exist
`409`	`CONFLICT`	Resource already exists (e.g., duplicate domain)
`422`	`UNPROCESSABLE_ENTITY`	Request is well-formed but semantically invalid
`429`	`RATE_LIMITED`	Too many requests — retry after `Retry-After` header
`500`	`INTERNAL_ERROR`	Unexpected server error
`502`	`MAIL_ENGINE_ERROR`	Mail engine delivery failed

Handling Errors in the SDK

import {
  WistMail,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NotFoundError,
  WistMailError,
} from 'wistmail'
 
try {
  await wm.emails.send({ /* ... */ })
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key')
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited — retry in ${err.retryAfter}s`)
  } else if (err instanceof ValidationError) {
    console.error('Bad request:', err.details)
  } else if (err instanceof NotFoundError) {
    console.error('Resource not found')
  } else if (err instanceof WistMailError) {
    console.error(`[${err.code}] ${err.message}`)
  }
}

Rate Limit Behavior

When rate limited (429), the response includes a Retry-After header indicating how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

The SDK raises RateLimitError with a retryAfter / retry_after property. Implement exponential backoff or respect the header value before retrying.

Idempotency

Email send endpoints accept an Idempotency-Key header to prevent duplicate sends when retrying:

curl -X POST https://mail.wistfare.com/api/v1/emails \
  -H "X-API-Key: wm_..." \
  -H "Idempotency-Key: order-12345-confirmation" \
  -H "Content-Type: application/json" \
  -d '{ "from": "...", "to": "...", "subject": "...", "html": "..." }'

If the same key is used within 24 hours, the original response is returned without sending again.

Error Response Format

Status Codes

Handling Errors in the SDK

Rate Limit Behavior

Idempotency

On this page