Errors

Every code the API returns, the status it comes with, and what to do about it.

A refusal is JSON with a code in it, and prose saying what to do about it. The prose is there because the thing reading the error is often a coding assistant halfway through wiring up a signup flow, and "the domain is not verified" is only actionable next to "verify it here, or send from onboarding@emails.sh while testing".

There are two body shapes#

Most of the API answers with a nested object: code, which is stable and safe to switch on; message, which says what happened; and next, which says what to do about it. This is the shape you get from /v1/emails, /v1/domains, /v1/webhooks, /v1/api-keys, /v1/audiences, /v1/broadcasts, /v1/segments, /v1/automations, /v1/analytics, /v1/ips, and the tag, attribute, and subscription routes under /v1/contacts/:id.

{
  "error": {
    "code": "invalid_from_domain",
    "message": "the domain acme.com is not verified on this workspace",
    "next": "Verify it at https://emails.sh/dashboard/domains, or send from onboarding@emails.sh while you are testing."
  }
}

A handful of routes still answer with a flat body instead: error is the code itself as a string, and message and hint are optional siblings rather than nested. Those routes are /v1/topics, /v1/suppressions, /v1/templates, the /v1/contacts collection and item routes including /v1/contacts/duplicates, and the rate limiter, which means a 429 rate_limited is flat whichever endpoint produced it.

{
  "error": "template_not_published",
  "message": "Template welcome has no published version, so there is nothing to send.",
  "hint": "Publish one with POST /v1/templates/{id}/publish."
}

Parse tolerantly. Read error, and if it is an object take error.code, and if it is a string take it as the code. Five lines once in your client is cheaper than discovering the difference in production, and the codes themselves are the same vocabulary either way.

interface Refusal {
  code: string;
  message: string;
  next?: string;
}

// Both shapes, one function. error is either { code, message, next } or the
// code as a bare string with message and hint alongside it.
export function readRefusal(body: unknown, status: number): Refusal {
  const b = (body ?? {}) as Record<string, unknown>;
  const e = b.error;

  if (e && typeof e === 'object') {
    const nested = e as Record<string, unknown>;
    return {
      code: String(nested.code ?? 'internal_error'),
      message: String(nested.message ?? `HTTP ${status}`),
      next: typeof nested.next === 'string' ? nested.next : undefined
    };
  }

  return {
    code: typeof e === 'string' ? e : 'internal_error',
    message: typeof b.message === 'string' ? b.message : `HTTP ${status}`,
    next: typeof b.hint === 'string' ? b.hint : undefined
  };
}

Switch on the code. Do not match on message, next, or hint: the prose is deliberately improved over time, and code that greps it breaks when we make it clearer. Both SDKs do the normalising above for you and put the result on the error they throw, as code, message, and nextStep (next_step in Python).

The catalogue#

What to retry#

4xx other than 429

Never retry unchanged. The request was wrong and it will be wrong the second time. Fix the body or the key.

429

Wait the number of seconds in retry-after, then send once. Backing off exponentially on top of that is fine; retrying in a tight loop is what gets a key throttled harder.

5xx

Retry with backoff, and pass idempotency_key so a retry that crossed with a success does not send twice.

A timeout with no response

The send may or may not have happened. Retry with the same idempotency_key: that is exactly what it is for.

The two you will actually hit#

invalid_from_domain means the from domain is not verified on this workspace. Either verify it at https://emails.sh/dashboard/domains, or send from onboarding@emails.sh while you are still testing. Nothing else clears it, and retrying will not.

sending_locked means nobody has confirmed the workspace owner's email address. It is the anti-abuse gate that stops a fresh signup being a free relay, and there is no card involved. Open the link in the confirmation email and it lifts immediately.