Errors, rate limits and quotas

Every failure comes back in one shape, and most of them mean something specific enough to act on.

The error envelope

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": [
      { "field": "recipients.0.email", "message": "Invalid email" }
    ]
  }
}

code is the contract and is safe to branch on. message is prose written for a human and may be reworded, so never match on it. details appears on validation errors and names each bad field - log it, or you are debugging blind.

Some errors carry extra keys alongside those three: requiredPlan on a 402, known_roles and missing_roles on a template send, file_ids on an unknown file, cap on a limit.

Status codes

Only 429 and 5xx are worth retrying automatically. Retrying a 400 or a 402 just produces the same failure more often.

Codes worth knowing by name

Rate limits

10 requests per minute per key. The limit is per key, so splitting work across several keys to go faster is circumventing it - ask for a higher limit if you have a genuine bulk need.

x-ratelimit-limit: 10
x-ratelimit-remaining: 8
x-ratelimit-reset: 42

x-ratelimit-reset is the seconds left in the current window and counts down toward zero. A 429 additionally carries a standard retry-after header, which is the simplest thing to honour.

async function withRetry(call, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    const res = await call();
    if (res.status !== 429 && res.status < 500) return res;
    if (i === attempts - 1) return res;

    const retryAfter = Number(res.headers.get("retry-after"));
    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : Math.min(2 ** i * 1000, 30_000);

    // Jitter, or every worker retries in the same instant.
    await new Promise((r) => setTimeout(r, waitMs + Math.random() * 250));
  }
}

Hard limits

What API sends cost

Business includes 40 API documents a month and Ultimate includes 200, flat per workspace rather than per seat. That is a free threshold, not a ceiling: document 41 still sends, billed at $0.40. Read usage on GET /account to see where you are in the current period.

A live API send counts against your normal monthly document allowance as well, because it is the same pool the web app draws from. Sandbox sends count against neither.

Mistakes worth avoiding

• Retrying a 4xx. Only 429 is retryable in that range.
• Branching on message. It is prose. code is the contract.
• Swallowing details on a 400. It names the exact field that is wrong.
• Retrying a send after a timeout without checking. The document may already exist. Look it up first, or you will send twice.