Errors

Every API error uses the same JSON shape, matching the Resend wire protocol:

{"statusCode": 422, "name": "validation_error", "message": "…"}

name is a stable machine-readable code (and the key the SDKs branch on); message is human-readable and may change. Branch on statusCode and name, never on message.

Error codes

Every code this deployment emits, by status. The same conditions reach the MCP server as tool results carrying this body, and the SMTP relay as its own protocol status — the names are the API's.

Sending pauses and holds

Three refusals mean "not now, and not because of your request". All three are 403 and deterministic — no retry loop clears them:

• sending_paused — the team's own hard-bounce or complaint rate over the trailing window is at or above the guardrail, so a send is refused before it reaches the queue. The message names the metric, the rate, the window and the limit. Clean the list and slow down until the rate falls back under the line; deliverability insights is the report that says which addresses caused it.
• broadcasts_paused — broadcast sending only (POST /broadcasts/{id}/send). Either the instance operator paused broadcasts for this team, or the platform's aggregate bounce/complaint rate in the sender's SES region is recovering and that whole region waits. Transactional email is unaffected, and it clears on its own.
• team_suspended — the instance operator suspended the team. Nothing sends until it is reinstated; only the operator can lift it.

Two protections run before mail reaches SES, on MepMail Cloud:

• A disguised sender is refused with 422 validation_error: a sender name or subject that mixes look-alike letters from different alphabets in one word (a Cyrillic а inside a Latin word), spells a word wholly in look-alike letters beside Latin ones, or hides invisible or direction-override characters. Write it in one alphabet and send again.
• A review hold keeps mail instead of sending it. A team in its first 30 days whose sender name or subject reads as a bank, a carrier, a tax office or an account-security notice, or whose payment was blocked by Stripe's fraud screening, is held for a short review. The API still answers 200 with the email id; the mail waits as queued and goes out when the review ends, and the dashboard shows the hold. Nothing is lost.

Retrying

• 4xx: retry only 409 concurrent_idempotent_requests (same idempotency key) and 429 (with backoff). Everything else in the 4xx range is deterministic — fix the request or the credential. 403 sending_paused, 403 broadcasts_paused and 403 team_suspended are deterministic too: waiting and retrying in a loop will not clear them.
• 5xx: retry with exponential backoff and jitter. Sends carrying an idempotency key are safe to retry; without one, a retried send can deliver twice.

Idempotency

Sending endpoints accept an Idempotency-Key header. Two requests with the same key run once; while the first is still executing, the second answers 409 concurrent_idempotent_requests. Reuse the same key when retrying after a timeout — that is what makes a retried send safe. Reusing a key with a different payload is 409 invalid_idempotent_request: give the new payload its own key instead of retrying.

Batch sends

POST /emails/batch accepts up to 100 emails. With the x-batch-validation: permissive header, invalid items are returned in errors by index while the valid subset is accepted; by default (strict), one invalid item rejects the whole batch. An over-cap array is a 422. A refusal that is not about one item — quota, a pause, the plan's contact cap — answers once for the whole call, in either validation mode.

MCP

The MCP server surfaces the same conditions: 429 rate_limit_exceeded on the endpoint when the account's call budget is exhausted, and tool-level failures as tool results with isError — read the text content for the code and message.