Mailchimp API rate limits: batching + backoff guide

Why you’re seeing 429s (and why “sleep 1 second” sometimes isn’t enough)

• Too much parallelism (thread pools, async fan-out, queue bursts)
• Long-running requests that keep connections open (even if your client times out)
• Multiple systems hitting the same Mailchimp account at once (e.g., AWS Lambdas + Zapier/Make + internal scripts)

The Mailchimp API batching + throttling playbook (high-level)

1. Batch size: 1,000–5,000 contacts per chunk (start at 1,000, scale up)
2. Concurrency cap: keep Mailchimp calls to a small number of concurrent requests (e.g., 2–8)
3. Exponential backoff: on 429 / 5xx, retry with growing delays + jitter
4. Idempotency: make every contact upsert safe to run multiple times
5. Queueing: prevent “bursts” from multiple triggers (Zapier/Make/AWS)
6. Monitoring + checkpoints: record progress so you can resume without redoing everything

Step 1: Choose a safe batch size (and why 5,000 is a good ceiling)

• keep each batch within runtime limits (Lambda timeouts, job timeouts)
• checkpoint progress (batch N of M)
• re-run only failed batches

• 1,000 contacts/batch if you’re brand new to this workflow
• 5,000 contacts/batch once stable (often a sweet spot: fast, but easier to retry than massive “do it all” runs)

Step 2: Cap concurrency (the #1 fix)

• a bounded worker pool
• a small max concurrency limit
• a single shared rate limiter for all Mailchimp API traffic in the system

Node.js example: concurrency-limited workers (p-limit)

import pLimit from "p-limit";

const limit = pLimit(6); // start 2–6, increase only after stable

async function upsertMember(member) {
  // Make your Mailchimp request here
  // Prefer upserts (PUT) over “create then update”
}

await Promise.all(
  members.map((m) => limit(() => upsertMember(m)))
);

Step 3: Add exponential backoff (with jitter) on 429 and transient 5xx

Node.js example: exponential backoff wrapper

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function withBackoff(fn, { maxRetries = 5, baseMs = 500 } = {}) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const status = err?.response?.status;

      // retry 429 and typical transient server errors
      const retryable = status === 429 || (status >= 500 && status <= 599);
      if (!retryable || attempt === maxRetries) throw err;

      const exp = baseMs * Math.pow(2, attempt);
      const jitter = Math.floor(Math.random() * 250);
      await sleep(exp + jitter);
    }
  }
}

• Start with 3–5 retries.
• Use jitter to avoid “thundering herd” retries.

Step 4: Make your writes idempotent (so retries don’t corrupt data)

• Use upsert patterns (e.g., PUT member by subscriber hash) rather than “create then update”.
• Treat every operation as “set desired state” not “apply a delta”.
• Persist a checkpoint (batch index + last processed contact) so you can resume.

• start over (wasteful), or
• guess what’s missing (risky)

Step 5: Reduce requests with the Batch endpoint (when appropriate)

• it reduces your need to maintain many concurrent connections
• it moves long-running work onto Mailchimp’s infrastructure
• it’s easier to monitor batch completion

• you are regularly syncing thousands of contacts
• you’re hitting timeouts or concurrency limits frequently
• you need predictable throughput

Step 6: Zapier/Make throttling patterns (to prevent bursts)

• Delay by queue (single queue key for “Mailchimp”) so events are serialized
• A “gatekeeper” step that checks whether a job is already running
• One “import worker” endpoint that processes jobs from a queue instead of running imports directly from each zap/scenario

Step 7: Monitoring + alerting (keep it boring in production)

• last successful run time
• batches attempted / succeeded / failed
• count of 429s and 5xx errors
• average request latency
• how many contacts were skipped due to validation issues

Common gotchas (learned the hard way)

• Client timeouts don’t mean the server stopped working. Mailchimp may still be processing requests, which keeps your concurrent connections “occupied.”
• Empty or invalid fields can fail a whole operation in some update flows. Validate inputs before sending (especially required merge fields).
• When you scale from a test list to a real list (tens of thousands), concurrency interactions are what change most dramatically — not your code logic.

Quick checklist

Get help building this