Errors

Returned for two distinct reasons: schema validation failures (wrong or missing fields) and domain-level validation (domain not verified, bad scheduledAt, etc.). The shapes are different.

Schema validation — Zod error

When a required field is missing or a field has the wrong type, the validator returns the raw Zod result. Each item in issues names the field via path and the problem via message:

// HTTP 400 — missing required field
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["from"],
        "message": "Required"
      }
    ],
    "name": "ZodError"
  }
}Copy

Domain not verified

// HTTP 400
{
  "error": "Sending domain not verified",
  "domain": "mail.yourdomain.com"
}Copy

Invalid from address

// HTTP 400
{
  "error": "Invalid from address",
  "domain": ""
}Copy

Too many recipients

// HTTP 400
{
  "error": "Too many recipients: 75. Maximum is 50.",
  "count": 75,
  "max": 50
}Copy

Invalid or past scheduledAt

// HTTP 400 — not a valid datetime
{ "error": "Invalid scheduledAt datetime" }

// HTTP 400 — in the past
{ "error": "scheduledAt must be a future datetime" }Copy

Returned when the Authorization header is missing, malformed, or contains an invalid or deleted API key.

// HTTP 401
{
  "error": "Unauthorized"
}Copy

Monthly email limit reached. The response tells you exactly where you are against your plan's cap.

Single send

// HTTP 402
{
  "error": "Monthly limit reached",
  "limit": 3000,
  "used":  3000,
  "plan":  "Starter"
}Copy

Batch — all-or-nothing pre-flight check

// HTTP 402
{
  "error": "This batch of 50 would exceed your monthly limit of 3000. You can send 12 more this month.",
  "canSend": 12
}Copy

The referenced resource does not exist or is not accessible from your account. On the public API surface, this is returned when the template field references a slug that does not match any saved template in your account.

// HTTP 404
{
  "error": "Template not found"
}Copy

Returned in two situations: a template fails to render, or a batch fails validation. The shapes are different — check for the errors array to distinguish them.

Template render failure — a {{variable}} in the template body has no matching key in the variables object. Handlebars strict mode is enabled, so every referenced variable must be provided.

// HTTP 422 — missing template variable
{
  "error": "Template render failed: \"firstName\" not defined"
}Copy

Batch validation failure — one or more emails in a POST /v1/emails/batch request are invalid. The batch is all-or-nothing: nothing is queued, and every invalid item is reported with its zero-based index in emails[].

// HTTP 422 — batch rejected, nothing queued
{
  "error": "Batch validation failed — no emails were queued",
  "errors": [
    { "index": 1, "error": "Sending domain not verified: unverified.com" },
    { "index": 4, "error": "scheduledAt must be a future datetime" }
  ]
}Copy

Returned for two independent limits: the per-minute request rate limit and the daily sending cap. The shapes are different — check the body to distinguish them.

Rate limit exceeded (100 requests / 60 seconds)

// HTTP 429
{
  "error": "Rate limit exceeded. Please slow down."
}Copy

Rate limit headers are returned on every request — check X-RateLimit-Remaining to throttle proactively before you hit this. See Conventions → Rate limits.

Daily sending cap — single send

// HTTP 429
{
  "error": "Daily sending limit reached",
  "dailyLimit": 100,
  "dailySent":  100,
  "resetsAt":   "midnight UTC",
  "plan":       "Starter"
}Copy

Daily sending cap — batch pre-flight

// HTTP 429
{
  "error": "This batch would exceed your daily limit of 100. You can send 20 more today.",
  "canSend": 20
}Copy

Account-level kill-switch. Quolle monitors bounce and complaint rates via CloudWatch. If either rate crosses a threshold, sending is automatically paused for the entire account to protect your domain reputation and inbox placement. This affects all sends regardless of template, recipient, or key used.

// HTTP 503 — bounce rate threshold exceeded
{
  "error": "Sending temporarily paused — account under review",
  "reason": "bounce"
}

// HTTP 503 — complaint rate threshold exceeded
{
  "error": "Sending temporarily paused — account under review",
  "reason": "complaint"
}Copy

An unexpected error occurred on our side. The body contains a message, but it may not always be actionable.

// HTTP 500
{
  "error": "Internal server error"
}Copy