Errors

Every error response uses one envelope:

{
  "error": {
    "type": "validation_error",
    "message": "The request was invalid.",
    "param": "to"
  }
}

Retry-relevant headers ride on the response itself. retry-after appears on rate_limit_exceeded, daily_quota_exceeded, account_under_review and volume_limit_reached; the ratelimit-* triple appears on rate_limit_exceeded alone and is stripped from every other 429. See Rate limits.

Catalog

invalid_api_key appears at both statuses. 401 means the key cannot be identified; 403 means a recognized key has been revoked. For why a bad credential surfaces as 401 even when a scope problem also exists, see Authentication.

See Troubleshooting, which routes domain verification, DNS, refused sends, and delivery failures to the page that fixes them, matched by error type or by symptom.

Handling errors

Branch on error.type, never on error.message. Messages are for humans and may change without notice.

The Node SDK never throws. Every method returns a { data, error } tuple, with the envelope's type, message, and param mapped onto the error object (transport failures have statusCode: null):

const { data, error } = await mailfully.emails.send(payload, {
  idempotencyKey: "order-1234-shipped",
});

if (error) {
  switch (error.type) {
    case "rate_limit_exceeded":
    case "daily_quota_exceeded":
    case "service_unavailable":
      // transient: back off, then resend with the same idempotency key
      break;
    case "validation_error":
      // error.param names the offending field, e.g. "from" or "[3].to"
      break;
    case "unverified_domain_required":
    case "account_suspended":
      // one-time setup problem: verify a sending domain
      break;
    case "account_under_review":
    case "volume_limit_reached":
    case "payment_past_due":
    case "monthly_quota_exceeded":
    case "marketing_quota_exceeded":
    case "spend_cap_exceeded":
      // Retrying right away won't help. Alert a person. The 24-hour
      // limits clear as the window moves; the monthly ones last until the
      // next month or a plan change.
      break;
    default:
      // log with error.statusCode, error.type, error.message
  }
} else {
  console.log(data.id);
}

The same pattern applies to raw HTTP: read the JSON body, switch on error.type, and treat the HTTP status as a coarse hint rather than the decision point.