Error handling

MailingCoreError — status codes, detail messages, and recovery.

The SDK throws MailingCoreError for API error responses (4xx/5xx).

Basic pattern

import { MailingCore, MailingCoreError } from 'mailingcore-js'

try {
  await MailingCore.send({
    to: '[email protected]',
    subject: 'Hello',
    htmlBody: '<p>Hi</p>',
  })
} catch (err) {
  if (err instanceof MailingCoreError) {
    console.error(err.status)   // 429
    console.error(err.detail)   // "Monthly email quota exceeded"
    console.error(err.type)     // optional machine-readable type
  } else {
    throw err // network, timeout, init errors
  }
}

Common status codes

Status	Meaning	Action
`400`	Invalid payload	Fix request fields
`401`	Invalid or missing API key	Check key and authentication
`403`	Missing scope or tenant	Review API keys and scopes
`404`	Resource not found	Verify template version ID
`429`	Rate limit or quota exceeded	See Rate limits and Quota headers
`500`	Server error	Retry with backoff; contact support if persistent

Non-API errors

Error	Cause
`MailingCore not initialized`	Call `MailingCore.init()` first
`Request timed out after Nms`	Increase `timeout` in init or check network
`AbortError`	Request exceeded configured timeout

Retry guidance

429 (rate limit) — wait for X-RateLimit-Reset or exponential backoff
429 (quota) — upgrade plan or wait for billing cycle
5xx — retry with idempotencyKey to avoid duplicates
4xx (except 429) — do not retry without fixing the request