Error reference

Every error response carries the same JSON envelope. Branch on code, never on the error prose or the HTTP status alone — code is the stable machine key; error is a human sentence that may change; details is optional structured context.

{
  "error": "This mailbox restricts agent sends to approved recipients.",
  "code": "RECIPIENT_AGENT_CONTAINED",
  "details": {
    "reason_axis": "recipient_containment",
    "remedy": "add_recipient_to_allowlist",
    "cheapest_next_step": "no_cost_remedy"
  }
}

• HTTP status groups the class of failure (4xx caller, 5xx transient). Use it for a coarse retry decision; use code for the precise cause and remedy.
• details is present on some codes only. Two families put machine-routable data there: the denial envelope (capability denials) and the RATE_LIMITED variants. Everything else is a bare { error, code }.

This page is the single source for the error-code catalog. For the order gates are checked on a send, see /agents/send-gates; for the four governed send outcomes see /agents/send-outcomes; for message states and scan-verdict vocabulary see /agents/messages; for the attachment staging lifecycle see /agents/attachments; for CLI exit codes see /agents/cli.

Denial envelope (capability 403 / 429)

Capability denials — "your plan/credential/mailbox setting/capacity won't allow this" — emit a denial envelope in details so you can route on the response instead of parsing prose. Detect one by the presence of details.reason_axis:

{
  "error": "This feature requires the pro plan or above.",
  "code": "TIER_LIMIT",
  "details": {
    "reason_axis": "tier",
    "remedy": "upgrade_tier",
    "required_tier": "pro",
    "cheapest_next_step": "pro",
    "upgrade_url": "https://app.replylayer.ai/settings/billing"
  }
}

reason_axis is a closed enum — exactly why the request was denied. remedy is the matching action. Switch on reason_axis first, then read the typed sibling field the remedy points at.

Field notes:

• upgrade_url attaches only on the monetary axes (tier, trust_capacity, account_state, sandbox_recipient) and only when a public dashboard link base is configured. It is omitted, never null — a non-monetary denial (a session swap, a mailbox toggle) deliberately carries no billing link so it can't misdirect you toward "upgrade".
• cheapest_next_step is the smallest money that unblocks you: paygo | starter | pro, or no_cost_remedy when the fix is a session/setting/time, not spend. On a tier denial, required_tier is the minimum plan; cheapest_next_step: "paygo" beside required_tier: "starter" means pay-as-you-go credit also unlocks the feature, and the error message names both. A Pro-only feature carries cheapest_next_step: "pro".
• Typed context may include feature, required_tier, current_tier, required_mailbox_mode, effective_daily_limit, current_count, max_allowed, attestations_limit, attestations_remaining. Every field is an enum, number, or server-derived URL — never free-form operator text.
• An agent cannot self-serve key_role, account_policy, or accountability_floor denials. These require a human dashboard session (with fresh re-auth for the loosening ones). In particular, loosening instruction trust is a dashboard-session + re-auth action only — an API key can never enable it for itself.

RATE_LIMITED disambiguation

RATE_LIMITED (HTTP 429) is overloaded: it covers failed authentication, your daily send quota, a new-account warm-up burst limit, and generic short-window throttles. Branch on the shape of details, not on the code:

Check the discriminators in this order. First, details.reason === "failed_authentication" on its own → the key is wrong or revoked: stop and fix it (a valid key is never refused by this block). Next, the presence of details.daily_limit → daily quota: wait for the reset or buy capacity. Next, details.reason === "new_account_warmup" → retry after retry_after_seconds. Only what remains (details.retry_after, or no details) is a generic short-window limit, answered by "wait a moment and retry". One no-details case to know: an address that has produced more than 600 failed key lookups in the current minute gets 429 for every key, valid or not, until the minute ends (it carries Retry-After). Tier and quota values live at /docs/limits.

Content blocks are not always a 4xx

A scanner block on a synchronous send/reply is folded into the message's terminal state and returns success-shaped unless you opt into strict outcomes with Prefer: outcome=strict (then it surfaces as EMAIL_EFFECT_REJECTED, below). The draft send path always fails loud (DRAFT_REJECTED_BY_RESCAN, 409). See /agents/send-outcomes for the governed-outcome contract.

Scan findings themselves are not error codes — they live on the message's scan_result_json. Two per-finding fields are agent-relevant:

• failure_class — "inference_error" marks an infrastructure failure (a scanner timeout/outage), not a content judgment. Such findings also carry retryable: true, and the customer-facing reason collapses to a static infrastructure string. A held or blocked send with failure_class: "inference_error" is safe to retry as-is; a genuine content block ("model_judgment") is not — edit the content or escalate.
• agent_instructions[] — optional, machine-readable handling guidance computed structurally from typed fields (vendor-free, index-agnostic). Present on non-allow findings that have concrete guidance; absent on inference_error.

Verdict vocabulary (quarantined vs blocked, releasable vs terminal) is documented at /agents/messages.

Code catalog

HTTP status, cause, denial reason_axis (where applicable), who can fix it, and whether a straight retry can succeed. "Who fixes" is agent (your key can recover), admin (an account admin, dashboard), or human (a dashboard session, sometimes with re-auth).

Authentication

SMS-based MFA & step-up re-auth

SMS is an alternative second factor to an authenticator app, and an SMS code is also the fresh re-auth on the session-only loosening gates. The ceremonies these codes belong to (enroll, method switch, SMS-disable proof, lost-factor recovery, phone change, and the scoped step-up send) are dashboard-session-only — an API key gets REAUTH_REQUIRES_SESSION (above) before any of them fires, so an agent integration never hits them directly. The two transient SMS send failures (MFA_SMS_RATE_LIMITED, MFA_SMS_UNAVAILABLE) can also surface on the public SMS login step. Catalogued here for completeness.

Authorization & scope

Send gates — recipient policy

Fired at send/reply/draft time. The evaluation order and preflight pattern are documented at /agents/send-gates.

Send gates — mailbox, domain & account state

Governed send outcomes (strict mode)

Emitted only when the caller sets Prefer: outcome=strict on send/reply and the send did not deliver. Without the header these outcomes surface success-shaped. Full contract: /agents/send-outcomes.

Content sanitization (outbound)

Drafts & review

Attachments

Staging + preview codes. The upload → poll → consume-once lifecycle is documented at /agents/attachments.

Idempotency

The immediate-send idempotency contract keys on the Idempotency-Key header. A repeat of a proven send replays the prior outcome (same message_id) rather than erroring.

Rate limits, quota & capacity

Billing

Send-path billing gates. Managing billing is a human/admin dashboard action.

Validation & transport

Retry semantics in one line

• 5xx (INTERNAL_ERROR, UPSTREAM_ERROR, DOMAIN_UNAVAILABLE/_UNHEALTHY, WAIT_UNAVAILABLE, WEBHOOK_CREATE_RETRY, EMAIL_EFFECT_HELD_INFRA) and short-window 429s → retry with backoff.
• IDEMPOTENT_REQUEST_IN_FLIGHT / _NOT_PROVEN_SENT / ATTACHMENT_SCAN_PENDING / ATTACHMENT_PREVIEW_PENDING → poll/retry after the indicated window.
• Content blocks (EMAIL_EFFECT_REJECTED, DRAFT_REJECTED_BY_RESCAN, the OUTBOUND_HTML_* rejects) → never retry unchanged; edit the content, unless the finding carries failure_class: "inference_error" (retryable: true).
• Capability denials (any details.reason_axis) → apply the remedy; most need a human/admin, and none can be resolved by re-sending the same request.
• Authentication failures (UNAUTHORIZED, API_KEY_REVOKED, and the 429 with details.reason: "failed_authentication") → stop and fix the key; never retry.

The RATE_LIMITED daily-budget path and idempotency guards are proven never to double-charge or double-send on a retry.