title: "Errors" description: "The MachineMail API error envelope, every error type and the messages each area returns, plus agent onboarding and MCP errors and how to handle them." canonical: "https://machinemail.dev/docs/reference/errors"

Errors

The MachineMail API error envelope, every error type and the messages each area returns, plus agent onboarding and MCP errors and how to handle them.

Source: https://machinemail.dev/docs/reference/errors

The envelope

Every /v0 error, and errors from /health, /inbound/* and /auth/*, has this body:

{
  "error": {
    "type": "validation",
    "message": "username may contain a-z, 0-9 and . _ + - (1-64 characters)",
    "param": "username"
  }
}

There is no list of field errors: a validation error reports the first problem found.

Types

not_implemented is not in the OpenAPI ErrorResponse enum, but the API returns it.

A 401 always carries:

WWW-Authenticate: Bearer resource_metadata="https://api.machinemail.dev/.well-known/oauth-protected-resource"

An unknown route returns 404 with Route not found: <METHOD> <path>.

Messages by area

These are the messages the API returns today. param is shown where it is set.

Requests

Authentication and scope

Inboxes

Sending

The OpenAPI description of inbox status says sends to a paused inbox return 403 with code inbox_paused. The API returns 403 with type forbidden and the message above; there is no inbox_paused code in the body.

URLs (webhooks and attachment URLs)

400 when a URL is not http(s), contains credentials, points at a private or loopback address, or does not resolve. Examples: url must be an http(s) URL, url must point at a public host.

Other resources

Raw injection (POST /inbound/raw)

Plan limits

Free plan limits (how they are enforced) refuse a request with 402 plan_limit_exceeded. Paid plans are never refused, except past their trusted domains limit. The body has four extra fields:

{
  "error": {
    "type": "plan_limit_exceeded",
    "message": "The Free plan allows 100 messages a day (inbound messages and outbound recipients together); this organization has used 98 and this send needs 3. The allowance resets 2026-10-15T00:00:00Z. Upgrade at https://machinemail.dev/app/billing.",
    "param": "to",
    "limit_key": "messages_per_day",
    "limit": 100,
    "used": 98,
    "resets_at": "2026-10-15T00:00:00.000Z"
  }
}

Sends, replies, reply-all, forwards and draft sends return the send errors; MCP send tools return the same envelope in structuredContent. A scheduled draft that reaches a limit stays scheduled and is sent after the reset. Inbound mail past a Free limit is never refused to the sender: it is held.

Agent onboarding errors

/agent/* and /oauth2/* follow OAuth conventions instead of the envelope. Their bodies look like this and carry Cache-Control: no-store:

{
  "error": "authorization_pending",
  "error_description": "The claim has not been completed yet",
  "message": "The claim has not been completed yet"
}

Human claim lookups in the dashboard (GET and POST /auth/claim) use the standard envelope: 400 user_code must be 6 digits, 404 Claim code (unknown or expired) not found, 403 This agent can only be claimed by <masked email>, 429 Too many claim attempts....

MCP errors

MCP tools report API errors as a tool result with isError: true. The text content is <type>: <message> and structuredContent is the error envelope above. Transport errors (wrong method, server failure) are JSON-RPC errors with code -32000.

Handling errors

• Retry 429 after the number of seconds in Retry-After, when present.
• Do not retry 402 before resets_at (also in Retry-After). Without resets_at, waiting does not help: change the request or upgrade.
• Retry 500 with backoff. Do not blindly retry sends: a send that timed out may have gone out. Use drafts with a client_id when you need a retry-safe send.
• Do not retry 400, 403, 404 or 409 without changing the request.