What does HTTP 429 “Too Many Requests” mean and how do I avoid it?

An HTTP 429 response means you’ve hit Bead’s rate-limit quota for the API action you’re calling. The server has temporarily blocked further requests from your access token / IP until the limit resets.

1 — Default sandbox & production limits

Endpoint class	Production	Sandbox
Write (POST / PUT / DELETE)	60 requests / minute	30 requests / minute
Read (GET)	600 requests / minute	300 requests / minute

Detailed per-method limits are documented on the Rate Limits & Throttling page. Heavy load tests? Contact Bead support for a temporary lift.

2 — Anatomy of a 429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 35       ← Seconds until quota resets
RateLimit-Limit: 60   ← Quota for this window
RateLimit-Remaining: 0

• Retry-After — wait at least this many seconds before retrying.

• RateLimit-Remaining — how many calls you have left in the current 60-second window.

3 — Strategies to stay below the limit

Technique	How it helps
Use webhooks instead of polling	Webhook events push updates in real time—no need for frequent GET /payments/tracking loops.
Batch / cache reads	Store results locally for 30–60 s rather than re-fetching the same record.
Exponential back-off	On any 429, sleep for Retry-After, then double the wait time for repeated hits.
Stagger concurrency	Spread parallel jobs across a wider time window; randomize start times.
Prioritise writes	If your read traffic is close to the quota, reserve head-room for critical writes.
Request higher limits	Email [email protected] with traffic stats; we can raise quotas for proven production workloads.

4 — Reference back-off snippet (Node.js)

async function callApi(fn) {
  let delay = 0;
  while (true) {
    if (delay) await new Promise(r => setTimeout(r, delay * 1000));
    const res = await fn();
    if (res.status !== 429) return res;              // success or other error

    const retryAfter = Number(res.headers["retry-after"] || 1);
    delay = Math.max(retryAfter, delay ? delay * 2 : retryAfter);
  }
}

5 — Debug checklist

• Check headers — RateLimit-Remaining shows your live balance.

• Look for bursts — Logs often reveal one noisy loop that can be throttled.

• Verify auth scopes — Separate service accounts reduce shared quota clashes.

• Audit retries — A 400 / 401 bug that retries instantly can snowball into 429s.

Still seeing 429s after optimization? Send request IDs or timestamps to [email protected] and we’ll analyze the traffic pattern.