# Error codes

Every error from the eMailPlane API has the same shape. The `code` never changes meaning, so your app or agent can branch on it.

```json
{ "error": {
    "code": "scope.forbidden",
    "message": "token lacks the scope required by this endpoint",
    "retryable": false,
    "human_action": true,
    "remedy": "Ask the app owner for a credential with one of the required scopes.",
    "next": "GET /v1/tokens/self",
    "docs_url": "https://emailplane.com/developers/errors/#scope-forbidden",
    "required_scope": "send",
    "granted_scopes": ["read:inbox"]
} }
```

| Field | Meaning |
|---|---|
| `code` | Stable and machine-readable. Branch on this, not on the message. |
| `message` | One line for a person. It never repeats an email address or a token back to you. |
| `retryable` | `true` when the same request can succeed later without you changing anything (a busy server, a spent hourly budget). |
| `human_action` | `true` when a person has to do something first: approve, change a policy, hand a conversation back, or issue a new credential. |
| `remedy` | What to do, in a sentence or two. When the server knows something more specific, this says it. |
| `next` | A call that tells you more or gets you unstuck, when there is one. |
| `docs_url` | This page, at the code. |

Some errors add details, such as `field`, `reason`, `retry_after_seconds` or `required_scope`. Your server lists every code with `GET /v1/errors`, and one with `GET /v1/errors/{code}`.

## Credentials and permission

### `auth.missing`

**No credential was sent.** Retry can work: no. A person must act: no.

Send `Authorization: Bearer <token>` with a token from your server. Next: `GET /v1/tokens/self`.

### `auth.invalid`

**The credential is not valid.** Retry can work: no. A person must act: yes.

The token is unknown, malformed or revoked. Ask the app owner for a new one; retrying the same token will not help.

### `auth.rate_limited`

**Too many sign-in attempts.** Retry can work: yes. A person must act: no.

Wait for the time in `Retry-After`, then try once. Retrying sooner extends the lockout.

### `scope.forbidden`

**This credential lacks the permission.** Retry can work: no. A person must act: yes.

The body lists the scopes the endpoint accepts and the ones you hold. Ask the app owner for a credential with one of the required scopes. Next: `GET /v1/tokens/self`.

### `role.forbidden`

**Your role cannot do this.** Retry can work: no. A person must act: yes.

No credential you can create fixes this; an operator or the owner has to do it.

### `tier.forbidden`

**Your plan does not include this.** Retry can work: no. A person must act: yes.

The body names the capability and the plan that includes it. Mail you already have keeps working. Next: `GET /v1/usage`.

### `plan.limit_reached`

**Your plan’s allowance is used up.** Retry can work: no. A person must act: yes.

The body shows the limit, what is used and what is included. Upgrade, add on, or free one up. Nothing that already exists is affected. Next: `GET /v1/usage`.

### `credential.inbox_bound`

**This credential is limited to one inbox.** Retry can work: no. A person must act: no.

An inbox credential can read and send only as its own inbox, and only on inbox endpoints. Use an app-wide credential for anything else. Next: `GET /v1/tokens/self`.

## The request

### `request.invalid`

**The request is not valid.** Retry can work: no. A person must act: no.

Fix the field named in `field` (and `reason`, when present), then send again.

### `validation.template_unresolved_tokens`

**The template needs more values.** Retry can work: no. A person must act: no.

Supply a value for every placeholder the body lists, then send again.

### `request.too_large`

**The request body is too large.** Retry can work: no. A person must act: no.

Send a smaller body; `limit_bytes` is the ceiling for this endpoint.

### `idempotency.mismatch`

**That Idempotency-Key was used for a different request.** Retry can work: no. A person must act: no.

Use a new key for a new request. A key always returns the first answer it was given.

### `conflict`

**It conflicts with what already exists.** Retry can work: no. A person must act: no.

Read the current state, then decide whether your change is still needed.

### `not_found`

**Not found.** Retry can work: no. A person must act: no.

Nothing with that id exists for this app. An id that belongs to another app reads the same way, on purpose.

## Sending limits and reputation

### `quota.exceeded`

**Today’s sending quota is used up.** Retry can work: yes. A person must act: no.

The quota resets at midnight UTC (`retry_after_seconds`). An operator can raise it. Next: `GET /v1/tokens/self`.

### `rate.capped`

**Sending is capped for now.** Retry can work: yes. A person must act: no.

The cap follows this credential’s bounce and complaint record and lifts by itself as that improves. Next: `GET /v1/reputation`.

### `budget.exhausted`

**The sending budget is spent.** Retry can work: no. A person must act: yes.

Complaints and bounces used up this credential’s sending budget. Clean the list; an operator can grant more. Next: `GET /v1/reputation`.

### `stream.quarantined`

**This stream is paused.** Retry can work: yes. A person must act: no.

This one stream (transactional or bulk) is paused after complaints; your other stream still sends. Stop the mail that caused it and wait for the gradual reopen. Next: `GET /v1/enforcement`.

### `queue.backpressure`

**The server is catching up.** Retry can work: yes. A person must act: no.

Nothing is wrong with your request. Wait for `Retry-After`, or send it as transactional mail.

### `send.unavailable`

**Sending is unavailable right now.** Retry can work: yes. A person must act: no.

A safety check the send path never skips could not run, so nothing was sent. Try again shortly.

### `plane_mail.daily_cap`

**Today’s account-mail allowance is spent.** Retry can work: yes. A person must act: no.

This credential sends the service’s own account mail (invites, receipts, reminders), which has its own daily limit and shares a daily ceiling with relayed mail. It resets by itself: wait for `Retry-After`. Next: `GET /v1/plane-mail/status`.

### `plane_mail.braked`

**Account mail is paused after complaints.** Retry can work: no. A person must act: yes.

Too many recipients reported this account mail as spam, so it stopped. An operator has to review it and turn it back on; retrying will not help. Next: `GET /v1/plane-mail/status`.

## Recipients

### `recipient.forbidden`

**This server may not deliver to that recipient yet.** Retry can work: no. A person must act: yes.

Delivery is limited to an allowlist the operator controls until this server is cleared to send to anyone. No credential changes that.

### `recipient.suppressed`

**That recipient is suppressed.** Retry can work: no. A person must act: no.

They complained, hard-bounced or unsubscribed. Remove them from your list; only an operator can lift it. Next: `POST /v1/suppressions/check`.

## Inboxes and reading mail

### `inbox.not_active`

**That inbox no longer receives mail.** Retry can work: no. A person must act: no.

The inbox was burned or has expired. Create a new one. Next: `POST /v1/inboxes`.

### `inbox.no_service_domain`

**This app has no domain for inboxes yet.** Retry can work: no. A person must act: yes.

Inboxes are created at the app’s own domain. Set one up first.

### `address.taken`

**That address is already in use.** Retry can work: no. A person must act: no.

Choose another local part, or leave it out to get a random one.

### `address.burned`

**That address was burned.** Retry can work: no. A person must act: no.

A burned address is never issued again, so an old user’s mail cannot reach a new one. Choose another.

### `address.reserved`

**That address is reserved.** Retry can work: no. A person must act: no.

Names such as postmaster and abuse belong to the mail system. Choose another.

### `view.agent_content_only`

**The agent view returns text only.** Retry can work: no. A person must act: no.

Agents read the cleaned, wrapped text. HTML and raw bytes are not available in the agent view.

### `withheld.human_only`

**Only a person can open this message.** Retry can work: no. A person must act: yes.

The message was withheld from agents (a lookalike sender, hidden content or a failed DMARC check). A signed-in person can review it.

### `wait.limit_reached`

**Too many waits are open.** Retry can work: yes. A person must act: no.

Cancel or let some waits finish before arming another. Next: `GET /v1/waits`.

## Agents: policy, drafts and conversations

### `agent.paused`

**Sending is paused for this agent.** Retry can work: no. A person must act: yes.

Someone pulled the kill switch for this credential, its inbox or the app. A person or an admin resumes it. Next: `GET /v1/send-policy`.

### `agent.self_resume`

**A credential cannot lift its own pause.** Retry can work: no. A person must act: yes.

A signed-in person, or another admin credential, resumes it.

### `loop.auto_submitted`

**That message was sent by a machine.** Retry can work: no. A person must act: no.

Mail from auto-responders, mailing lists and bounce systems is never answered automatically, so two machines cannot reply to each other forever.

### `loop.circuit_open`

**Too many sends into one conversation.** Retry can work: yes. A person must act: no.

The per-conversation limit stops a reply loop. It reopens after the window in your send policy. Next: `GET /v1/send-policy`.

### `budget.tool_calls`

**This hour’s call budget is spent.** Retry can work: yes. A person must act: no.

Wait for the next hour (`Retry-After`), or ask a person to raise `tool_calls_per_hour` in the send policy. Next: `GET /v1/send-policy`.

### `draft.not_pending`

**That draft was already decided.** Retry can work: no. A person must act: no.

A draft is approved, rejected or expires once. Read it to see what happened.

### `approval.human_only`

**Only a person can approve or reject.** Retry can work: no. A person must act: yes.

Drafts are decided in the dashboard, or by replying APPROVE or REJECT from the approver’s mailbox. No credential can decide one.

### `thread.human_owned`

**A person has taken this conversation.** Retry can work: no. A person must act: yes.

Do not answer. You can offer a reply with a draft; only a person hands the conversation back. Next: `POST /v1/drafts`.

### `thread.handback_human_only`

**Only a person can hand a conversation back.** Retry can work: no. A person must act: yes.

Handing a conversation back to an agent is a person’s (or an admin’s) decision.

## The server

### `internal`

**Something went wrong on the server.** Retry can work: yes. A person must act: no.

Try again. If it keeps happening, the server log has the details; error bodies never do.

## From the MCP server

These come from the MCP server itself, when the request never reached the API. They carry the same fields.

### `infra.control_plane_unreachable`

**The MCP server could not reach the API.** Retry can work: yes. A person must act: no.

The eMailPlane API runs on your own server; check that it is running and that the MCP server is configured with its address, then try again.

### `infra.unparseable_response`

**The API answered with something that is not JSON.** Retry can work: yes. A person must act: no.

Something between the MCP server and the API answered with a page that is not JSON. Try again; if it persists, check the proxy in front of the API.

### `custody.mailbox_handoff_unavailable`

**A mail-app password cannot be issued over MCP yet.** Retry can work: no. A person must act: yes.

A person’s mail-app password cannot be handed over safely through MCP yet. Nothing was changed; ask the owner to issue it from the dashboard.

### `handoff.activation_unconfirmed`

**The new credential is saved but not yet confirmed active.** Retry can work: yes. A person must act: no.

The new credential is saved in its local file. Call the same tool again with the same idempotency key to confirm it is active.

---

Source: https://emailplane.com/developers/errors/