> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/what-does-http-429-too-many-requests-mean-and-how-do-i-avoid-it.md).

# 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/what-does-http-429-too-many-requests-mean-and-how-do-i-avoid-it.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.