# 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
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 <developers@bead.xyz> with traffic stats; we can raise quotas for proven production workloads. |

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

```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 [**developers@bead.xyz**](mailto:developers@bead.xyz) and we’ll analyze the traffic pattern.