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, and the dry runs send simulate / propose) can actually return. The CLI's own guidance for each reason comes from one table, and a test checks that every reason in it appears on this page; the descriptions here are kept by hand. Journey steps and follow-ups record the same reasons on the send's trace (see Journeys).

For errors outside the send path (auth, scopes, approvals, team addresses and so on), see Other error codes.

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

Mailbox create and restore errors

These are error codes from creating or restoring a mailbox, not send reasons:

Coordination and safety

Held for human approval (status: "pending_approval")

The response also carries a human-readable message for each reason.

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.

A whole batch over 500 entries is refused before anything runs: 400 { "error": "batch_too_large", "message", "field", "max": 500, "received" } (also on simulate-batch, batch/next-best-action and batch/classify-intent).

Single-send request errors

These are refused with an HTTP error before the policy engine runs, and nothing is sent:

Suppression reasons

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

When you add a suppression yourself, reasonCode can be complaint, hard_bounce, manual_dnc, legal_request, role_account, domain_suppressed or no_engagement.

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. The kind names what is held:

The /v1/override/* routes are also reachable as /v1/agent/override/*.

{
  "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; the message then says only a person can approve or release messages on it). 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"]
}

The same loosenings are gated on their other routes too: autonomy also through PATCH /v1/agent/mailboxes/:id/autonomy and PATCH /v1/mailboxes/:id; safety settings through PUT /v1/agent/config/safety-settings, PUT /v1/ops/safety-settings and PUT /v1/spam-filter/rules; the humanizer through PUT /v1/agent/config/humanizer, PUT /v1/ops/humanizer and, for one agent, PUT /v1/agent/agents/:agentId/config (kind: "agent-config").

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, mailbox-address 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.

If a person changes the same control while an agent's request is being checked, and the agent's change would now loosen what is stored, the answer is 409 settings_changed with the loosens list, and nothing is written. Read the settings again and retry.

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

Loosenings with no portal screen

Most loosenings have somewhere to go in the portal: a person resumes a mailbox or the account, raises autonomy, creates or manages a key, and edits the spam-filter rules and the humanizer under Settings > Safety. Five kinds do not. A decisionUrl for them opens a page that explains what the agent asked for; it has no form to make the change. This is how a person makes each one today:

There is no self-serve way to make the last three changes yet: an agent key is refused on a workspace in enforce mode, the default, and a person has nothing to click. On a workspace in off mode, or in warn mode while its warning period lasts, an agent key can make them directly.

The safety settings have a smaller version of the same gap. The portal edits only the six spam-filter fields; a person changes the per-verdict actions and the guardrail flags with PUT /v1/me/safety-settings and their portal session. See Safety Settings.

Billing decisions

Starting checkout through the session route (POST /v1/billing/checkout), opening the billing portal, and ending a trial early ("start now") are 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. They follow the workspace's human-gate mode like the loosenings above (enforce answers 403, warn lets it through with a deprecation header, off allows it). The session routes are owner-only (403 Only the workspace owner can manage billing first), and POST /v1/billing/start-now with a key also needs admin scope on all mailboxes. 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",
  "loosens": ["agent-held session"]
}

(loosens is on the session-route answer; the key route's start-now answer has none.)

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:

{
  "statusCode": 403,
  "error": "free_plan_requires_human",
  "message": "The Free plan needs a person as the owner. This workspace is agent-owned, so activate-free is refused. Run `molted auth login-link --next /app/settings#plan` (POST /v1/agent/login-token) and follow what it returns...",
  "plans": ["solo", "team"],
  "setupLinkRoute": "/v1/billing/setup-link",
  "loginLinkRoute": "/v1/agent/login-token",
  "loginLinkCommand": "molted auth login-link --next /app/settings#plan",
  "claimRoute": "/v1/me/principal/upgrade"
}

To get Free, run molted auth login-link --next "/app/settings#plan" (POST /v1/agent/login-token) and follow what it returns: when the account's email is your human's own inbox, Molted emails them a link to set their password and take the account over; when it is one of your Molted mailboxes, you get a claim link to give them (see Links for your human). Once they are done, activate-free succeeds, also with your existing key. Or buy a paid plan 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.

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

{
  "statusCode": 403,
  "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:

{
  "statusCode": 403,
  "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"
}

The checks run in that order (agent-owned, then unverified, then disposable). Activating from a plan other than trial is a 400 (Cannot activate free plan from "<plan>" plan. Only trial accounts can activate the free tier.), as is a workspace whose plan is set by Molted support.

GET /v1/billing/status never advertises "activate_free" in actions unless the owner already qualifies, and its activateFreeBlockedReason names which of the three applies, 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:

{
  "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.

Other error codes

Machine-readable codes the API returns outside the send path. Most come as error in the body; ones marked (message) come as the message of a plain error.

Auth and scope

Approvals and held items

Plans, team addresses and limits

Suppressions, labels and lists

Request IDs

Every response from the API and from the mailbox host carries an x-request-id header, errors included. When a request goes through the mailbox host to the API, both services use the same ID, so one ID follows the call all the way.

An error body repeats the ID as traceId:

{
  "statusCode": 404,
  "message": "Thread not found",
  "error": "Not Found",
  "traceId": "cor_0f3a9c1d5b7e4a2c8d6e1f0a3b5c7d9e"
}

The field is traceId, never requestId: requestId in a send response means the send request, not the HTTP request. Most CLI commands print the error body under detail, so the traceId is in their output.

You can set the ID yourself. An x-request-id (or x-correlation-id) of 8 to 128 characters made of letters, digits, ., _, : and - is kept as sent; anything else is replaced with one Molted makes, so a malformed value never travels on. That lets a caller tag a request and find it again in its own logs.

Quote the ID when you report a problem. Molted keeps a short record of each failed request for 30 days, found by this ID: the route, the status, the error code, which workspace and which kind of caller. Never a request body and never an email address. Failures on the portal, agent and claim routes and on the mailbox host are kept, except 401 answers, which are not recorded.

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