Email API rate limits: the ratelimit headers, the 429, and backoff that never sends twice

curl -si "${RASKET_API_URL:-https://api.rasket.com}/domains" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" | grep -iE '^(HTTP|ratelimit-|retry-after)'

HTTP/1.1 200 OK
ratelimit-limit: 10
ratelimit-remaining: 9
ratelimit-reset: 1

// burst.mjs: fifteen GETs at once: more than the bucket holds. Run it once, not in a loop.
const api = process.env.RASKET_API_URL ?? "https://api.rasket.com";
const headers = {
  authorization: `Bearer ${process.env.RASKET_API_KEY}`,
  "user-agent": "acme-billing/1.0",
};

const responses = await Promise.all(
  Array.from({ length: 15 }, () => fetch(`${api}/domains`, { headers })),
);

for (const [i, response] of responses.entries()) {
  const h = (name) => response.headers.get(name) ?? "-";
  console.log(
    `#${i + 1} ${response.status} remaining=${h("ratelimit-remaining")} reset=${h("ratelimit-reset")} retry-after=${h("retry-after")}`,
  );
}

const refused = responses.find((response) => response.status === 429);
if (refused) console.log(await refused.json());

#1 200 remaining=8 reset=1 retry-after=-
#2 200 remaining=5 reset=1 retry-after=-
#3 200 remaining=7 reset=1 retry-after=-
#4 200 remaining=2 reset=1 retry-after=-
#5 200 remaining=0 reset=1 retry-after=-
#6 200 remaining=6 reset=1 retry-after=-
#7 200 remaining=4 reset=1 retry-after=-
#8 200 remaining=3 reset=1 retry-after=-
#9 429 remaining=0 reset=1 retry-after=1
#10 429 remaining=0 reset=1 retry-after=1
#11 429 remaining=0 reset=1 retry-after=1
#12 429 remaining=0 reset=1 retry-after=1
#13 429 remaining=0 reset=1 retry-after=1
#14 200 remaining=1 reset=1 retry-after=-
#15 429 remaining=0 reset=1 retry-after=1
{
  statusCode: 429,
  name: 'rate_limit_exceeded',
  message: 'Too many requests. You can only make 10 requests per second.'
}

// send-with-backoff.mjs: Node 22+, no dependencies.
const api = process.env.RASKET_API_URL ?? "https://api.rasket.com";

// Retry these names. Every other refusal, quotas included, is thrown to the caller.
const RETRY = new Set(["rate_limit_exceeded", "concurrent_idempotent_requests"]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// maxWaitMs: the longest one wait may block this caller. Past it, the error carries
// retryAfterMs so a queue can run the job again later instead of holding a worker asleep.
export async function sendWithBackoff(message, idempotencyKey, { maxAttempts = 5, maxWaitMs = 30_000 } = {}) {
  const payload = JSON.stringify(message); // outside the try: a bad message is a bug, not a retry
  let delay = 500; // the wait when no retry-after came; doubles after each retry
  for (let attempt = 1; ; attempt++) {
    let response;
    try {
      response = await fetch(`${api}/emails`, {
        method: "POST",
        headers: {
          authorization: `Bearer ${process.env.RASKET_API_KEY}`,
          "content-type": "application/json",
          "user-agent": "acme-billing/1.0",
          "idempotency-key": idempotencyKey, // the same on every attempt
        },
        body: payload,
        signal: AbortSignal.timeout(10_000),
      });
    } catch (error) {
      // No answer (network failure or our timeout): it may or may not have been sent.
      // The key makes the retry safe. Anything else is a bug in this code: rethrow it.
      const lost = error.name === "TimeoutError" || (error.name === "TypeError" && error.cause);
      if (!lost) throw error;
      if (attempt === maxAttempts) throw error;
      await sleep(delay + Math.random() * delay);
      delay = Math.min(delay * 2, maxWaitMs);
      continue;
    }

    const body = await response.json().catch(() => null); // null: not JSON, or cut off
    if (response.ok && body) return { ...body, attempts: attempt };

    // A 200 whose body was lost is retried too: the same key returns the same id.
    const retryable = response.ok || RETRY.has(body?.name) || response.status >= 500;
    if (!retryable || attempt === maxAttempts) {
      const reason = body?.name ? `${body.name}: ${body.message}` : response.statusText;
      throw Object.assign(new Error(`${response.status} ${reason}`), {
        status: response.status,
        apiName: body?.name,
      });
    }

    const retryAfter = Number(response.headers.get("retry-after")); // whole seconds
    const base = retryAfter > 0 ? retryAfter * 1000 : delay;
    if (base > maxWaitMs) {
      throw Object.assign(new Error(`${response.status}: retry in ${base / 1000} s`), {
        status: response.status,
        apiName: body?.name,
        retryAfterMs: base,
      });
    }
    await sleep(Math.min(base + Math.random() * base, maxWaitMs)); // jitter, never past the cap
    delay = Math.min(delay * 2, maxWaitMs);
  }
}

const email = await sendWithBackoff(
  {
    from: "Acme <billing@acme.example>",
    to: ["ronald.williams@example.com"],
    subject: "Invoice 1042",
    html: "<p>Your invoice is attached.</p>",
  },
  "invoice-1042",
);
console.log(email);

# send_batches.py: Python 3.10+, standard library only.
import email.utils
import http.client
import json
import os
import random
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone

API = os.environ.get("RASKET_API_URL", "https://api.rasket.com")
RETRY = {"rate_limit_exceeded", "concurrent_idempotent_requests"}


def seconds_to_wait(retry_after, default):
    """Retry-After is whole seconds or an HTTP date (RFC 9110). Rasket sends seconds."""
    try:
        return max(int(retry_after), 1)
    except (TypeError, ValueError):
        pass
    try:
        when = email.utils.parsedate_to_datetime(retry_after)
        return max((when - datetime.now(timezone.utc)).total_seconds(), 1)
    except (TypeError, ValueError):
        return default  # absent or unreadable


def post_batch(messages, idempotency_key, max_attempts=5, max_wait_seconds=30):
    """max_wait_seconds: the longest one sleep may block. Past it, raise and let the queue retry later."""
    delay = 0.5
    for attempt in range(1, max_attempts + 1):
        request = urllib.request.Request(
            f"{API}/emails/batch",
            data=json.dumps(messages).encode(),
            method="POST",
            headers={
                "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
                "Content-Type": "application/json",
                "User-Agent": "acme-billing/1.0",
                "Idempotency-Key": idempotency_key,  # the same on every attempt
            },
        )
        try:
            with urllib.request.urlopen(request, timeout=10) as response:
                return json.load(response), response.headers
        except urllib.error.HTTPError as error:
            try:
                body = json.loads(error.read())
            except ValueError:
                body = {}  # not JSON: a proxy's error page, say
            retryable = body.get("name") in RETRY or error.code >= 500
            if not retryable or attempt == max_attempts:
                raise RuntimeError(f"{error.code} {body.get('name')}: {body.get('message')}")
            wait = seconds_to_wait(error.headers.get("retry-after"), delay)
        except (OSError, ValueError, http.client.HTTPException):
            # No answer, or it stopped halfway: refused, reset, timed out, or a 200
            # whose body was cut off. Retry with the same key: it returns the same ids.
            if attempt == max_attempts:
                raise
            wait = delay
        if wait > max_wait_seconds:
            raise RuntimeError(f"retry in {wait:.0f} s")  # longer than this worker should sleep
        time.sleep(min(wait + random.uniform(0, wait), max_wait_seconds))  # jitter, capped
        delay = min(delay * 2, max_wait_seconds)


def send_invoices(job_id, invoices):
    invoices = sorted(invoices, key=lambda invoice: invoice["id"])  # same cut on every run
    for n, start in enumerate(range(0, len(invoices), 100)):  # a batch holds at most 100
        chunk = invoices[start : start + 100]
        messages = [
            {
                "from": "Acme <billing@acme.example>",
                "to": [invoice["email"]],
                "subject": f"Invoice {invoice['id']}",
                "html": "<p>Your invoice is attached.</p>",
            }
            for invoice in chunk
        ]
        result, headers = post_batch(messages, f"{job_id}-batch-{n}")
        for invoice, sent in zip(chunk, result["data"]):
            print(invoice["id"], sent["id"])  # in real code: record it as sent
        if headers.get("ratelimit-remaining") == "0":  # pace before the next request
            time.sleep(int(headers.get("ratelimit-reset") or 1))


send_invoices(
    "invoices-2026-10",
    [{"id": 1042 + n, "email": "ronald.williams@example.com"} for n in range(3)],
)

curl -s "${RASKET_API_URL:-https://api.rasket.com}/billing" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" |
  python3 -c 'import json, sys; u = json.load(sys.stdin)["usage"]; print(json.dumps({k: u[k] for k in ("emails", "included_emails", "emails_today", "daily_limit", "daily_limit_reason", "monthly_limit")}, indent=2))'

{
  "emails": 123,
  "included_emails": 100000,
  "emails_today": 123,
  "daily_limit": null,
  "daily_limit_reason": null,
  "monthly_limit": 100000
}