# Errors

Every Groundmail API error is JSON with a stable `code`, a human `message`, a `hint` that says how to fix it, and a `docs_url` that links to the matching section of this page. Branch on `code`, show `message` to people, and follow `hint` when you are an agent or a retry loop.

## Shape

```json
{
  "error": {
    "code": "forbidden",
    "message": "Sandbox sends are limited to owner@example.com. Verify your domain and add a payment method at /settings/billing to send to other recipients.",
    "hint": "Sandbox sends from noreply@mail.groundmail.dev only go to your own account email. Send the test to that address, or verify your domain (POST /domains, then apply and verify) and add a payment method at https://app.groundmail.dev/settings/billing to send to anyone.",
    "docs_url": "https://docs.groundmail.dev/errors#forbidden",
    "upgrade_url": "/settings/billing"
  }
}
```

| Field | Always present | Meaning |
|-------|----------------|---------|
| `code` | Yes | Stable, machine-readable code from the list below. New codes may be added; existing codes do not change meaning. |
| `message` | Yes | What went wrong, in plain English. Wording can change, so do not parse it. |
| `hint` | Yes | What to do next. Specific to the failure when we know more (for example a sandbox recipient), otherwise the default for the code. |
| `docs_url` | Yes | `https://docs.groundmail.dev/errors#<code>` |
| `details` | No | Structured context, such as `suppressed` recipients or a domain `reason`. |
| `upgrade_url` | No | Dashboard path to fix a plan or billing limit. |
| `required_scope` | No | With `insufficient_scope`: the scope the endpoint needs, space-separated when there are several. |

A few older endpoints (domain verify and apply, webhook update, dashboard integrations) return `error` as a string. They carry the same fields beside it, so the same parsing works for both:

```json
{
  "error": "Domain not found",
  "code": "not_found",
  "message": "Domain not found",
  "hint": "Check the id. Ids are scoped to the team that owns the API key; list the collection (for example GET /domains or GET /emails) to find a valid id.",
  "docs_url": "https://docs.groundmail.dev/errors#not_found"
}
```

Read errors defensively:

```ts
const body = await res.json()
const err = typeof body.error === 'object' ? body.error : body
console.error(err.code, err.message, err.hint)
```

Every API response has an `x-request-id` header (`req_…`). Quote it when you write to support, or send it with [`POST /feedback`](https://docs.groundmail.dev/cli#report-a-problem), which `groundmail feedback` does for you.

The Node SDK throws a `GroundmailError` with `status`, `code`, `message`, `hint`, `docsUrl`, `details`, `requestId`, and, when they apply, `requiredScope` and `upgradeUrl`:

```ts
import { Groundmail, GroundmailError } from 'groundmail'

try {
  await groundmail.domains.create({ name: 'example.com' })
} catch (err) {
  if (err instanceof GroundmailError && err.code === 'insufficient_scope') {
    console.error(`Needs ${err.requiredScope}: ${err.hint} (${err.docsUrl})`)
  }
}
```

## Recovering without a human

1. Look at `code`, not `message`.
2. `validation_error`, `not_found`, `conflict`, `forbidden`, `insufficient_scope`, `domain_not_allowed`, `tenants_not_enabled`, `newsletter_not_enabled`, `stream_paused`, `recipient_not_allowed`, `unauthorized`: fix the request as `hint` says. Sending the same request again returns the same error.
3. `rate_limited`, `internal_error`, `not_configured`, and `upstream_error` with status `502` or `503`: retry with exponential backoff (for example 1s, 2s, 4s, 8s, up to 5 tries). Honor `Retry-After` when it is set. An `upstream_error` with `504` means the email may already be on its way: check before resending.
4. For sends, put an `Idempotency-Key` header on the first attempt and reuse it on every retry, so a retry can never send the same email twice. See [Test sends and idempotency](https://docs.groundmail.dev/ai/safe-defaults).
5. `plan_limit` and `domain_limit` need a person (turning on pay as you go, or cleanup). Stop and report `upgrade_url`. `daily_ramp_limit` is a daily ramp-up limit (a new account's, or a tenant's when `details.tenant` is set): there is no `upgrade_url`, so wait until `details.resets_at` (the next 00:00 UTC) and send the rest then. A tenant's limit only holds that tenant's mail.

## Error codes

### validation_error {#validation_error}

**Status:** `400`, or `422` when the request was valid but a recipient cannot receive it.

The body, query or headers failed validation: a missing `from`/`to`/`subject`, a malformed address, an unpublished template, an `Idempotency-Key` longer than 256 characters, or invalid JSON. `422` is used when every recipient is suppressed (`details.suppressed`) or opted out of the email's category (`details.category_unsubscribed`).

**Fix:** read `message` and `details`, correct the field and send again. Field names and types are in the [OpenAPI spec](https://docs.groundmail.dev/openapi.yaml). Do not retry a `422` to the same recipients.

### unauthorized {#unauthorized}

**Status:** `401`

The `Authorization` header is missing, is not `Bearer gm_…`, or names a revoked or unknown key.

**Fix:** send `Authorization: Bearer gm_…` with an active key. Create or copy one at [app.groundmail.dev/api-keys](https://app.groundmail.dev/api-keys) and load it from an environment variable such as `GROUNDMAIL_API_KEY`. Never put the key in browser code.

### forbidden {#forbidden}

**Status:** `403`

The key is valid, but this account or request is not allowed to do this. The common causes, each with its own `message` and `hint`:

| Cause | Fix |
|-------|-----|
| `from` is on a domain this team has not verified | Verify the domain ([Domains](https://docs.groundmail.dev/domains)), or test from `noreply@mail.groundmail.dev` to your own account email |
| Sandbox send (`from` is `noreply@mail.groundmail.dev`) to someone other than your account email | Send the test to your account email |
| Verified domain, Free plan, no payment method, recipient is not your account email | Add a payment method at [Billing](https://app.groundmail.dev/settings/billing). Free is not charged. |
| Sending is restricted on the account | Contact contact@groundmail.dev. Retrying will not help. |
| The key's scope does not allow this endpoint (older keys) | Use a full-access key |
| The [tenant](https://docs.groundmail.dev/tenants) is paused (`details.tenant_status: "paused"`) | Resume it with `PATCH /tenants/{tenant}` and `{"status":"active"}`. If Groundmail paused it (`pause_source` `automated` or `admin`), fix the list and contact support@groundmail.dev. |
| The tenant is `transactional_only` and the email is product email | Send with `category: "transactional"`, or change the tenant's `stream_policy` |
| The API key is limited to one tenant and the request is for another tenant, or for an endpoint tenant keys cannot use | Leave `tenant` out (the key sends as its tenant), or use an account key. See [Limit a key to one tenant](https://docs.groundmail.dev/api-keys#limit-a-key-to-one-tenant). |
| The API key is limited to mailboxes and the request is for an endpoint such keys cannot use | Use an account key. See [Limit a key to mailboxes](https://docs.groundmail.dev/api-keys#limit-a-key-to-mailboxes). |
| A [mailbox](https://docs.groundmail.dev/mailboxes#who-can-send-what) can't send this: a hosted address emailing first or answering a sender who didn't pass DMARC, a reply to a DMARC fail or to automatic mail, a conversation moving too fast, or cold outreach (`details.reason`) | Read `message`. Retrying won't help. Use a mailbox on your own domain, or leave this one for a person. |
| The mailbox is paused or forwarding | A paused mailbox says why in `paused_reason`: fix that, then `PATCH /mailboxes/{id}` with `{"status":"active"}`. A forwarding one can't send: send from its new mailbox. |

### insufficient_scope {#insufficient_scope}

**Status:** `403`

The API key's scope does not cover this endpoint, for example a send-only key calling a management endpoint.

**Fix:** use a key whose scope includes the endpoint, or create one at [app.groundmail.dev/api-keys](https://app.groundmail.dev/api-keys). Give agents the narrowest key that does the job. `required_scope` names the scope the endpoint needs; see [Authentication](https://docs.groundmail.dev/authentication#scopes).

```json
{
  "error": {
    "message": "This API key lacks the `domains:write` scope. Create a key with that scope in Settings → API keys.",
    "code": "insufficient_scope",
    "required_scope": "domains:write",
    "hint": "Use an API key whose scope includes this endpoint, …",
    "docs_url": "https://docs.groundmail.dev/errors#insufficient_scope"
  }
}
```

### domain_not_allowed {#domain_not_allowed}

**Status:** `403`

The API key is limited to specific sending domains and `from` uses a different one. `details` lists the allowed domains and the domain you sent from. It is also returned when `from` is on a domain that belongs to a different [tenant](https://docs.groundmail.dev/tenants) than the one the send is for (`details.tenant`, `details.from_domain`).

**Fix:** send from a domain the key allows, or edit the key's allowed domains (or create a new key) at [app.groundmail.dev/api-keys](https://app.groundmail.dev/api-keys). For a tenant, send from one of its own domains (`GET /tenants/{tenant}/domains`) or an account-wide domain.

### tenants_not_enabled {#tenants_not_enabled}

**Status:** `403`

The request names a [tenant](https://docs.groundmail.dev/tenants) (`tenant` on a send, domain, suppression, API key or test event, `tenants` on a webhook, or a `/tenants` endpoint), but tenants are not enabled for this account. Tenants are included on pay as you go (up to 1,000) and Dedicated (up to 10,000), not on Free.

**Fix:** turn on pay as you go at [Billing](https://app.groundmail.dev/settings/billing), or contact support@groundmail.dev. To send from the account as a whole, remove `tenant` from the request. Retrying unchanged returns the same error.

### newsletter_not_enabled {#newsletter_not_enabled}

**Status:** `403`

The send uses `category: "newsletter"`, but newsletter sending isn't enabled on this account. Newsletter email is accepted only for approved accounts, and goes out from separate IPs from transactional and product email. Nothing was sent: Groundmail never sends a refused newsletter as another category.

**Fix:** email support@groundmail.dev to ask for approval. Until then, send transactional and product email as usual. Retrying unchanged returns the same error.

### stream_paused {#stream_paused}

**Status:** `403`

Product, newsletter or mailbox email is paused on this account (`details.stream` says which: `product`, `newsletter` or `agent`) after a high spam complaint or bounce rate. Transactional email still sends. Nothing was sent, and the email isn't queued to send later.

Before a pause, Groundmail reviews: at a 0.1% complaint rate the account owner gets an email and the dashboard shows a notice, and mail keeps sending. Product or newsletter email is paused at 0.5% (and at least 3 complaints), judged over the last 7 days when a day has fewer than 1,000 sends.

**Fix:** reply to the email Groundmail sent the account owner, or write to support@groundmail.dev, with what you were sending and how those people signed up. A person reviews it and resumes the stream. Retrying unchanged returns the same error until then. Don't resend product email as `transactional` to get around the pause.

### recipient_not_allowed {#recipient_not_allowed}

**Status:** `403`

The mailbox has a recipient allow list (`allowed_recipients`), and the send or reply names someone outside it. `details.refused` lists those addresses and `details.allowed_recipients` the list. Nothing was sent, to anyone.

**Fix:** remove the refused recipients and send again, or add them to the mailbox with `PATCH /mailboxes/{id}` and `allowed_recipients` (needs `mailboxes:write`). Retrying unchanged returns the same error. See [Mailboxes](https://docs.groundmail.dev/api/mailboxes).

### not_found {#not_found}

**Status:** `404`

No resource with that id exists for the team that owns the key.

**Fix:** check the id. List the collection (`GET /domains`, `GET /emails`, `GET /templates`, …) to find a valid one. Ids from another team are not visible.

### conflict {#conflict}

**Status:** `409`

The resource already exists, or its state blocks the change: a domain already added, a domain claimed by another team (`details.reason: "domain_claim_required"`), a template alias or automation name in use.

**Fix:** fetch the existing resource and reuse or update it instead of creating it again. Follow `details.instructions` when present.

### plan_limit {#plan_limit}

**Status:** `429`

The account reached its plan's sending limit: the Free plan's 3,000 emails a month or 100 a day. Pay as you go has no monthly stop: it's $15 a month with 20,000 emails included, then billed per 1,000 emails.

**Fix:** wait for the limit to reset, or turn on pay as you go at `upgrade_url`. Retrying now returns the same error. Send responses carry `ratelimit-limit`, `ratelimit-remaining` and `ratelimit-reset` headers for the monthly quota, so you can see the limit coming. When a daily limit applies, they also carry `ratelimit-daily-limit`, `ratelimit-daily-remaining` and `ratelimit-daily-reset` (Unix time of the next 00:00 UTC). All limits: [Sending limits](https://docs.groundmail.dev/sending-limits).

Batch sends (`POST /emails/batch`) check the limit for each email in order: emails within today's allowance are sent, and the rest come back with this error in their item. SMTP rejects a message over the limit with a permanent `554` reply carrying the same message.

`POST /mailboxes` uses this code too, with status `403`, when the account has reached its [mailbox](https://docs.groundmail.dev/mailboxes) allowance. Free stops at 3 mailboxes: delete one you no longer use, or turn on pay as you go at `upgrade_url`.

`POST /validate` and `POST /validate/batch` use it with status `403` when `mailbox_check` is set on the Free plan: the [mailbox check](https://docs.groundmail.dev/validation#mailbox-check) is charged, so it needs pay as you go. Turn it on at `upgrade_url`, or leave out `mailbox_check` for the free check.

### daily_ramp_limit {#daily_ramp_limit}

**Status:** `429`

The send would go over a new account's daily ramp-up limit for its stream (transactional or product), or over a [tenant](https://docs.groundmail.dev/tenants)'s own ramp or `daily_limit` (then `details.tenant` names the tenant, and only that tenant waits). New accounts start at 1,000 product and 3,000 transactional recipients a day (on the first two stages, email without a `category` counts as product, so send transactional email with `category: "transactional"`), and the limit doubles each day after you use at least half of it with bounces under 2% and complaints under 0.1%. How it works: [New accounts ramp up](https://docs.groundmail.dev/sending-limits#new-account-ramp-up).

**Fix:** do not retry now: nothing was sent, and the same send is refused until the limit resets. Send the rest after `details.resets_at` (the next 00:00 UTC). Turning on pay as you go does not lift it, so there is no `upgrade_url`. Moving an existing sender over and need more sooner? Email support@groundmail.dev.

Scheduled emails and automation send steps over the limit wait for the reset instead of failing (`last_event` `daily_ramp_deferred`), up to 3 times. SMTP answers with a temporary `451 4.7.1` reply that gives the reset time, so your mail server queues the message and retries it. Details: [When a send would go over the limit](https://docs.groundmail.dev/sending-limits#new-account-ramp-up).

`details` has `stream`, `daily_limit` (today's recipient limit for that stream), `used_today`, `recipients` (in this send), `ramp_stage` and `resets_at`, plus `tenant` when a tenant's limit refused the send. How tenants ramp: [Tenants](https://docs.groundmail.dev/tenants#sending-ramp).

```json
{
  "error": {
    "code": "daily_ramp_limit",
    "message": "New accounts ramp up their sending: today's limit for product email is 4,000 recipients, and this send would go over it. It resets at 00:00 UTC and grows as you send clean mail. Need more sooner? Email support@groundmail.dev.",
    "hint": "New accounts have a daily sending limit that doubles each day they use at least half of it with bounces under 2% and complaints under 0.1%. …",
    "docs_url": "https://docs.groundmail.dev/errors#daily_ramp_limit",
    "details": {
      "stream": "product",
      "daily_limit": 4000,
      "used_today": 3998,
      "recipients": 3,
      "ramp_stage": 3,
      "resets_at": "2026-10-20T00:00:00.000Z"
    }
  }
}
```

#### New account ramp-up {#new-account-ramp-up}

The ramp-up schedule and what counts toward it are on [Sending limits](https://docs.groundmail.dev/sending-limits#new-account-ramp-up).

### domain_limit {#domain_limit}

**Status:** `403`

The account reached its plan's domain limit (Free: 3, pay as you go: 1,000).

**Fix:** delete a domain you no longer use (`DELETE /domains/{id}`) or turn on pay as you go at `upgrade_url`.

### idempotency_conflict {#idempotency_conflict}

**Status:** `409`

The `Idempotency-Key` was already used with a different request body, or the first request with that key is still being processed.

**Fix:** use a new key for a new request. To retry the same request, send the identical body with the same key; if the first attempt is still running, wait a second and retry.

### rate_limited {#rate_limited}

**Status:** `429`

Too many requests in a short window. [Mailboxes](https://docs.groundmail.dev/mailboxes) use this code for their sending limits, new-recipient limits and fair-use read limits.

**Fix:** wait the number of seconds in `Retry-After`, then retry with exponential backoff. Reuse the same `Idempotency-Key` on retried sends.

### timeout {#timeout}

**Status:** `408`

A long-poll ended before anything matched: on `GET /test-inbox/wait`, no email to the address arrived within `timeout` seconds (`details` carries `to` and `timeout`); on `GET /mailboxes/{id}/wait`, no matching message did (`details` carries `mailbox`, `timeout` and `since`).

**Fix:** check that the email went to the exact address you are waiting on, then call again. The wait is safe to repeat. On `GET /test-inbox/wait` it returns an email that arrived in the meantime; on `GET /mailboxes/{id}/wait` pass `details.since`, so nothing is missed between calls. Each call waits at most 60 seconds; the SDK's `testInbox.waitFor` and `mailboxes.wait` repeat it for longer timeouts.

### upstream_error {#upstream_error}

**Status:** `502` or `503` (not sent, safe to retry), `504` (outcome unknown), or a `4xx` passed through when the mail server refused the message.

The mail server did not accept the request, or a DNS provider call failed during domain apply.

A send answered with `status: "queued"` never gets this error: Groundmail hands it to the mail server in the background and retries temporary problems for you for about 15 minutes. If the mail server refuses it, or the retries run out, the email's status becomes `failed` with a `bounce_reason` and an `email.failed` webhook fires. You can still get `upstream_error` on a send with attachments, which is handed over during the request.

**Fix:**

- `502` / `503`: the email was not sent. Retry with exponential backoff and the same `Idempotency-Key`.
- `504`: the email may still go out. Do not resend blindly: check `GET /emails` first. A retry with the same `Idempotency-Key` returns the same `504` instead of sending a duplicate.
- `4xx`: the message was refused. Fix it as `message` says and send with a new key.

If it keeps failing, contact contact@groundmail.dev with the request time.

### not_configured {#not_configured}

**Status:** `503`

The feature is not available on this deployment right now (for example image uploads, or sending during maintenance).

**Fix:** retry later. If it persists, contact contact@groundmail.dev.

### internal_error {#internal_error}

**Status:** `500`

Unexpected server error.

**Fix:** retry with exponential backoff and the same `Idempotency-Key`. If it keeps failing, contact contact@groundmail.dev with the request time.

## Status codes at a glance

| Status | Codes |
|--------|-------|
| `400` | `validation_error` |
| `401` | `unauthorized` |
| `403` | `forbidden`, `insufficient_scope`, `domain_not_allowed`, `tenants_not_enabled`, `newsletter_not_enabled`, `domain_limit` |
| `404` | `not_found` |
| `408` | `timeout` |
| `409` | `conflict`, `idempotency_conflict` |
| `422` | `validation_error` (suppressed or opted-out recipients) |
| `429` | `rate_limited`, `plan_limit`, `daily_ramp_limit` |
| `500` | `internal_error` |
| `502` | `upstream_error` |
| `503` | `not_configured`, `upstream_error` |
| `504` | `upstream_error` (outcome unknown) |

## Idempotency

`POST /emails` and `POST /events` accept an `Idempotency-Key` header. A retry with the same key and body returns the original response instead of sending again. Details: [Test sends and idempotency](https://docs.groundmail.dev/ai/safe-defaults).
