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

{
  "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.