Errors & Policy Blocks

When a send request is blocked by the policy engine, the response includes a reason field. A status: "pending_approval" response also carries a reason (why a human needs to decide) and a status: "scheduled" response may carry one too (why it was deferred rather than sent immediately). This page documents every reason the send path (molted send, threads reply, send batch) can actually return -- the same table the CLI itself is driven from (packages/cli/src/reasons.ts), so it can't drift out of sync the way this page once did.

Policy engine

Billing

Quota

Exceeding a send quota window blocks with the specific window's reason, never a generic rate_limited -- see Rate Limits for what counts toward each window.

Warmup and domain throttling

Template and content

Mailbox and domain resolution

Coordination and safety

Held for human approval (status: "pending_approval")

Review held items with molted overrides queue needs_approval; approving is human-only (molted auth login-link for a link to give them, or a human runs molted overrides approve <threadId>).

Deferred (status: "scheduled")

A scheduled response with no reason means the caller passed an explicit scheduledAt.

Batch item errors (results[].status: "error")

These are validation failures on one recipient in a send batch call, not policy blocks -- the rest of the batch is unaffected.

Suppression reasons

When a recipient is on the suppression list (suppressed block reason), the suppression was created for one of these reasons:

Validation errors

These errors are returned as 400 Bad Request before the policy engine runs. They indicate malformed input rather than a policy decision.

Validation errors return an array of messages describing each invalid field:

{
  "statusCode": 400,
  "message": ["recipientEmail must be an email"],
  "error": "Bad Request"
}

Human-only decisions

Approving, rejecting, releasing and editing held items is a decision for a person, not an agent. When an agent key makes one of these calls on an account that enforces this, the API answers 403:

{
  "error": "human_decision_required",
  "message": "This decision needs a human. Share the decisionUrl with a person on your team; they can approve or reject it in the Molted portal.",
  "decisionUrl": "https://molted.email/app/decide/send/APPROVAL_ID",
  "kind": "send",
  "id": "APPROVAL_ID",
  "reason": "enforce"
}

Don't retry. Send the decisionUrl to a person on your team. reason is enforce, warn_expired (the account's 30-day warning period is over) or thread_taken_over (a human has taken the thread over). See Approval Queues.

Loosening a control

Agents may make an account safer, never less safe. Pausing, lowering autonomy, tightening a safety check, turning the humanizer off and narrowing or revoking your own keys always work. Changes that loosen a control are human decisions, gated the same way as approvals: enforce answers 403, warn lets the call through with a Molted-Deprecation: human-gate header, off allows it.

A loosening attempt in enforce mode gets a 403 shaped like this (an autonomy raise, in this example):

{
  "error": "human_decision_required",
  "message": "Agents may tighten controls but not loosen them. This change needs a human: share the decisionUrl with a person on your team; they can make it in the Molted portal.",
  "decisionUrl": "https://molted.email/app/decide/autonomy/MAILBOX_ID",
  "kind": "autonomy",
  "id": "MAILBOX_ID",
  "reason": "enforce",
  "loosens": ["autonomyLevel 1 -> 3"]
}

loosens lists what the change would loosen. kind is mailbox-resume, account-resume, autonomy, safety-settings, humanizer, tenant-settings, agent-config, api-key, adopt-invite, suppression, domain-warmup, domain-rate-limits, contact or billing; for a key or invite that doesn't exist yet, id is new. Don't retry: send the decisionUrl to a person, or drop the loosening part of the change (a tightening on its own goes through). People signed in to the portal are never gated.

Pausing the whole account (not just one mailbox) is one such tightening/loosening pair -- pausing always works, resuming is usually gated the same way:

molted pause --reason "investigating a bounce spike"   # POST /v1/ops/pause -- always works
molted resume                                          # POST /v1/ops/resume -- usually needs a human, per the table above
molted incidents list                                  # GET /v1/ops/incidents -- always works
molted incidents ack <id>                              # PATCH .../incidents/:id {status: acknowledged} -- always works
molted incidents resolve <id>                          # PATCH .../incidents/:id {status: resolved} -- same gate as resume, if it's an open pause incident

Billing decisions

Starting checkout through the session route (POST /v1/billing/checkout), opening the billing portal, and ending a trial early ("start now") are always human decisions, even for an agent holding the workspace owner's own session (e.g. one created by molted auth signup): money changes need a person, no matter how the change would tighten or loosen anything else. This doesn't apply to the agent Bearer-token checkout route (POST /v1/billing/setup-link) -- see below.

{
  "error": "human_decision_required",
  "message": "Billing changes need a person. Open the link to manage the plan.",
  "decisionUrl": "https://molted.email/app/decide/billing/TENANT_ID",
  "kind": "billing",
  "id": "TENANT_ID",
  "reason": "enforce"
}

Don't retry: send the decisionUrl (or the link from molted auth login-link) to a person, or complete it yourself if you're a human on the portal's own session.

Free plan requires a verified human

Activating the Free plan (POST /v1/billing/activate-free) is a different kind of decision: it is refused outright, not delegated to a person via a decisionUrl, and it does not consult the workspace's human-gate mode -- warn or off don't loosen it. It succeeds only when the tenant's owner is a human account (principal_kind = 'human') with a verified email on a non-disposable domain.

An agent-owned tenant (e.g. one created by molted auth signup or any non-portal signup) gets:

{
  "error": "free_plan_requires_human",
  "message": "The Free plan is for verified humans only. This tenant is agent-owned, so activate-free is refused. Buy a paid plan instead...",
  "plans": ["solo", "team"],
  "setupLinkRoute": "/v1/billing/setup-link",
  "claimRoute": "/v1/me/principal/upgrade"
}

Buy a paid plan instead with POST /v1/billing/setup-link (molted billing setup --plan solo, or the billing_checkout_link MCP tool) -- agents may always request a checkout link, since a human still has to complete the Stripe-hosted page. Alternatively, have a human claim the account (POST /v1/me/principal/upgrade) and activate Free from there.

A human owner whose email isn't verified yet gets:

{
  "error": "email_verification_required",
  "message": "Verify your email before activating the Free plan. Check your inbox for the verification link, or resend it from the portal (Settings > Email)."
}

A verified human owner whose email domain is a known disposable provider (mailinator.com and the like) gets:

{
  "error": "disposable_email_not_allowed",
  "message": "The Free plan needs a real, reachable email address. Use one from a regular provider, or choose a paid plan instead...",
  "plans": ["solo", "team"],
  "setupLinkRoute": "/v1/billing/setup-link"
}

GET /v1/billing/status never advertises "activate_free" in actions unless the owner already qualifies, so an agent driven purely off actions won't hit this 403 in the first place. Existing Free tenants (activated before this rule shipped, or comped by an admin) keep their plan -- this never claws one back.

Plan limits on settings

Turning the humanizer on (PUT /v1/agent/config/humanizer with "enabled": true, or an agent's own humanizer_enabled) on a plan that doesn't include it (Free) is refused before any human decision:

{
  "statusCode": 403,
  "error": "humanizer_not_in_plan",
  "message": "The humanizer is not included in your plan. Upgrade to Solo (50 rewrites a month) or Team (300 a month) to turn it on.",
  "plan": "free"
}

Sends are never refused for this: a send whose rewrite will be skipped is accepted and carries warnings (see Humanizer).

Sending a previewed rewrite

A send with humanizePreviewId (Send exactly what you previewed) is refused, and nothing is sent, when the preview doesn't fit it. In a batch, only that recipient fails, with the code as its reason.

If the humanizer was turned off after the preview, the send is not refused: the original goes out with the warning humanize_preview_ignored_humanizer_off.

Handling blocked sends

1. Check the reason field in the response to understand why the send was blocked.
2. Refer to the tables above for the specific reason.
3. Take the appropriate action -- wait for a cooldown, verify a domain, upgrade your plan, etc.
4. Retry the request once the issue is resolved. Use a new dedupeKey if the original was consumed.

Related reading

• Why AI Agents Need Email Guardrails -- the failure modes these policy rules prevent
• How to Send Your First Policy-Checked Email -- see policy traces in action with a step-by-step tutorial