API errors

Every error response follows the same shape:

{
  "error": {
    "type": "validation_error",
    "message": "Subject is required",
    "code": "VALIDATION_ERROR",
    "request_id": "req_Hg8JpNvKXWg4f",
    "errors": [
      { "path": ["to", 0], "code": "invalid_string", "message": "Invalid recipient email" }
    ]
  }
}

• type — high-level category (also matches HTTP status below).
• code — stable identifier for programmatic handling; see catalog.
• message — human string; may reference the first field issue.
• request_id — also emitted as the X-Request-Id header. Include in support tickets.
• errors[] — present on validation errors from a Zod schema. Each row has path (array of keys / indexes), code (Zod issue code), message.

Types → HTTP status

Full code catalog

Authentication — 401 / 403

Validation — 409 / 413 / 422

Rate / quota — 429

Not found — 404

Server — 500

Provider — 502

When a downstream provider (AWS SES / SNS / Stripe) returns an error we couldn't classify, you'll see type: "server_error" with a 502 and the provider's message copied into message. Log the request_id and the provider trace if possible.

Reading validation errors

try {
  await mr.emails.send({ from, to, subject, html });
} catch (err) {
  if (err.code === "VALIDATION_ERROR") {
    for (const issue of err.errors ?? []) {
      console.log(issue.path.join("."), issue.message);
    }
  } else if (err.code === "RATE_LIMITED") {
    await new Promise((r) => setTimeout(r, reset - Date.now()));
  }
}

Headers

Returned on every response, not just 429:

X-Request-Id: req_Hg8JpNvKXWg4f
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1713820800
X-RateLimit-Plan: pro
X-RateLimit-Scope: org | key

Recovery recipes