Markdown

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.

Updated Nov 17, 202612 min read

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:

TypeScript
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, 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:

TypeScript
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.
  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

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. Do not retry a 422 to the same recipients.

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 and load it from an environment variable such as GROUNDMAIL_API_KEY. Never put the key in browser code.

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), 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. 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 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.
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.
A mailbox 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

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. Give agents the narrowest key that does the job. required_scope names the scope the endpoint needs; see Authentication.

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

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 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. For a tenant, send from one of its own domains (GET /tenants/{tenant}/domains) or an account-wide domain.

tenants_not_enabled

Status: 403

The request names a tenant (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, 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

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

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

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.

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

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

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.

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 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 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

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'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.

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.

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.

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

The ramp-up schedule and what counts toward it are on Sending limits.

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

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

Status: 429

Too many requests in a short window. 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

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

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

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

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.

Was this page helpful?