Errors and rate limits

Error shape

{
  "error": {
    "code": "validation_failed",        // stable, safe to branch on
    "message": "Human-readable, may change",
    "details": [{ "field": "to", "reason": "..." }],   // optional
    "requestId": "req_..."              // quote this to support
  }
}

/oauth/* is the exception: it follows RFC 6749 ({ "error", "error_description" }). See OAuth errors.

Error codes on /v1

Not every route can return every code; the OpenAPI document lists the statuses per operation. A tenant or resource in another project is always 404.

Held sends (new organisations)

A new organisation's first sends are reviewed by a human (first-send approval). While the approval is pending, POST /v1/emails still answers 202, but the email's status is held instead of queued. This is expected, not an error: held emails are delivered once Reach approves the organisation.

• What to do: nothing in your request is wrong. Contact Reach to get approved, or wait. Do not resend held emails; you would create duplicates.
• held is one of the email statuses everywhere a status is listed or filterable: queued, held, dispatching, sent, dispatch_unconfirmed, delivered, bounced, complained, failed, suppressed, canceled. Handle it explicitly in your code.
• Console side: GET /account/organizations/:id/sending-policy (a console-session endpoint, not callable with an API key or OAuth token) returns the organisation's plan ceiling, the approval state (sendApproval.status: pending or approved, with when and by whom) and heldEmailCount, the number of emails waiting right now. Approval itself is an operator action; there is no integrator API for it.

Send rate limits

There are two independent sources of a send 429, both enforced on every POST /v1/emails, both with three windows (per-second burst, per hour, per day):

The free plan's ceiling is 200 per day, 20 per hour and 5 per second for the whole organisation (the service's configured default; your plan's actual numbers are in the console).

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "error": {
    "code": "rate_limited",
    "message": "Too many emails: the "burst_per_second" rate limit was exceeded, try again later",
    "details": [{ "field": "window", "reason": "burst_per_second" }],
    "requestId": "req_..."
  }
}

• Retry-After is in seconds. details[0] is { "field": "window", "reason": "<window name>" }; the organization_ prefix is how you tell the plan ceiling from the per-tenant limit.
• A rate limit never blocks a retry of an already-accepted idempotencyKey.
• Always send an idempotencyKey so retries cannot double-send.

async function sendWithRetry(body, attempt = 0) {
  const res = await fetch("https://api.tryreach.email/v1/emails", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REACH_API_KEY}`,
      "Content-Type": "application/json",
    },
    // Same idempotencyKey on every attempt: a retry can never double-send.
    body: JSON.stringify(body),
  });
  if (res.status === 429 && attempt < 5) {
    const wait = Number(res.headers.get("retry-after") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return sendWithRetry(body, attempt + 1);
  }
  return res;
}

OAuth endpoint limits

The response is 429 slow_down with Retry-After. Honour it; do not loop.