Rate Limits

​

Overview

Rate limits and quotas protect the stability of the Boomerang Developer API and ensure fair use across all servers. This page explains:

• How monthly plans and credit packs work
• How requests are counted
• How hourly rate limits behave
• The headers returned with rate-limited responses
• How to plan and manage usage

Error codes and payloads for rate-limited responses are described on the Errors page.

---

​

Server-based quotas and credits

All usage is tracked per server, not per API key. Multiple keys for the same server share the same quota and credit pool. Each server has:

• A monthly plan (Free or Premium), which provides a set number of included requests per month.
• An optional credit balance, from one-off credit packs that roll over until used.

Monthly plan quota is always consumed before any credit balance. Plan quota resets each month; credits do not expire.

---

​

Plans and included requests

Monthly plans provide recurring included requests and an hourly rate limit per key. Plan rules:

• Free
  • Quota resets on the 1st of each month (GMT).
  • Hourly limits apply per key, but all keys draw from the same monthly pool for that server.
• Premium
  • Quota resets on the day of subscription renewal.
  • Hourly limits apply per key, with a shared monthly pool per server.
  • Premium can be purchased at https://bmrg.app/premium.

Once a server’s monthly included requests are exhausted, usage continues by consuming any available credit-pack balance.

---

​

Credit packs

Credit packs provide one-off, roll-over request balances that are added on top of any monthly plan. Credit rules:

• Credits are tracked per server and shared across all keys for that server.
• Credits never expire and are simply added to the existing balance when multiple packs are purchased.
• Monthly plan quota is used first; once plan quota reaches zero, successful requests consume from credit balance.
• When both plan quota and credit balance are exhausted, requests are rejected with a rate-limit or quota-exhausted error.

​

Buying credits

Credits can be purchased in the account section of the server’s dashboard.

---

​

What counts as a request

For quota and credit purposes, only successful authenticated requests count:

• Requests count when:
  • A valid API token is provided; and
  • The response is successful (2xx).
• Requests do not count when:
  • Authentication fails (for example, missing or invalid token).
  • The response is a 4xx or 5xx error (including validation errors, rate limits, or server errors).

All requests still remain subject to hourly rate limits, even if they do not consume quota or credits.

---

​

Hourly rate limits and burst behaviour

Hourly rate limits are enforced per key, using a sliding 60-minute window. The limits from the tables above apply. Key points:

• Each key has a maximum number of requests allowed in any rolling 60-minute period.
• Once that limit is reached, the key receives 429 responses until usage falls back under the threshold.
• All keys on a server can be active concurrently, but they share the same underlying monthly and credit pools.

To protect against short bursts, Boomerang may also apply soft per-second and per-minute controls. In practice, client implementations should:

• Avoid sending large bursts of traffic (for example, more than a few requests per second).
• Spread high-volume work over time instead of performing it in a single burst.

Exact burst thresholds may be adjusted to protect the platform, without reducing the documented hourly limits.

---

​

Rate-limit headers

When a request is rate limited or close to a limit, responses may include headers such as:

• X-RateLimit-Limit – the maximum number of requests allowed in the current window for this key.
• X-RateLimit-Remaining – remaining requests in the current window for this key.
• X-RateLimit-Reset – Unix epoch timestamp (in seconds or milliseconds) when the current window resets.
• X-Credits-Remaining – total remaining credit-pack balance for the server, if applicable.

Clients should use these headers to:

• Adjust behaviour dynamically (for example, back off when X-RateLimit-Remaining is low).
• Plan batch operations and background jobs to stay within limits.

---

​

Rate-limit errors and quotas

When limits are exceeded, the API returns HTTP 429 Too Many Requests with a structured error response as described on the Errors page. Common rate-limit and quota scenarios:

• Hourly limit exceeded for a key
  • HTTP status: 429
  • Behaviour: further requests from this key are rejected until the sliding window resets.
  • Error payload: includes a rate-limit error code and a hint indicating that the hourly limit was reached and when to retry.
• Monthly plan quota exhausted, credits available
  • HTTP status: 200 for successful requests.
  • Behaviour: usage continues, consuming from the server’s credit balance.
  • Headers: X-Credits-Remaining reflects the remaining credit-pack balance.
• All quota and credits exhausted
  • HTTP status: 429
  • Behaviour: further successful requests are rejected until the next monthly reset or additional credits are purchased.
  • Error payload: includes a specific error code indicating that quota/credits are exhausted and a hint indicating the next reset or that the user can purchase credits.

The exact error codes and example bodies are maintained in the Errors documentation to keep one canonical reference.

---

​

Client guidance

To work effectively with rate limits:

• Back off on 429
  • Do not retry immediately in a tight loop.
  • Use X-RateLimit-Reset and exponential back-off to schedule retries.
• Design for steady usage
  • Spread work over time instead of concentrating it into bursts.
  • Cache responses where appropriate to avoid repeated calls for the same data.
• Monitor usage
  • Track remaining quota and credits using the headers provided.
  • Alert when usage approaches thresholds so you can adjust behaviour or purchase additional credits.

If you consistently reach limits in normal, well-behaved operation, review your integration first, then consider moving from Free to Premium or adding credit packs for the relevant server.