# Rate Limits & Throttling

Bead enforces per-token rate limits on **terminal credentials** (`client_id = bead-terminal`). Every Hosted Payment Page (terminal) has its own quota. If you exceed that quota, the gateway returns **HTTP 429 Too Many Requests**.

### Default limits

| Environment    | Write calls(POST / PUT / PATCH / DELETE) | Read calls(GET)                          |
| -------------- | ---------------------------------------- | ---------------------------------------- |
| **Sandbox**    | 100 requests / minute / terminal token   | 1 000 requests / minute / terminal token |
| **Production** | 60 requests / minute / terminal token    | 600 requests / minute / terminal token   |

Entity-management APIs that use the `bead-integrator` client are low-volume and not metered by this limit; they may be capped separately in future.

### Rate-limit headers

| Header                  | Meaning                                               |
| ----------------------- | ----------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum calls allowed in the current 60-second window |
| `X-RateLimit-Remaining` | Calls still available after this request              |
| `X-RateLimit-Reset`     | Unix epoch time when the window resets                |

Example

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1717521120
```

### 429 response body

```json
{
  "code": 429,
  "error": "rate_limit_exceeded",
  "message": "Quota exhausted. Retry after 2 seconds."
}
```

If a `Retry-After` header is present, wait at least that many seconds before retrying.

### Best practices

* Monitor `X-RateLimit-Remaining` and slow down proactively when it falls below 10 % of the window.
* On 429, use exponential back-off: 1 s → 2 s → 4 s, then resume after `X-RateLimit-Reset`.
* Batch high-volume reads to stay within the GET quota; avoid bursts of parallel writes.
* Sandbox quotas are higher—test under production numbers before go-live.
* Need more headroom? Open a Support ticket with expected TPS and terminal count.

### FAQ

**Q • Are limits enforced per IP or per token?**\
A • Per terminal token. Calls from multiple IPs using the same token share its quota.

**Q • Do retries after a server error count?**\
A • Yes. Each request that reaches the gateway consumes one unit of quota.

**Q • Do webhook deliveries count against my limits?**\
A • No. Webhooks are outgoing from Bead and are not rate-limited.


---

# Agent Instructions: 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/reference-guide/core-concepts/rate-limits-and-throttling.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.