Honeycluster Docs – Rate Limits

Rate Limits

The public shared-tier fair-use ceiling, when you hit 429, and how enterprise plans get predictable dedicated capacity.

Honeycluster's public endpoint is open and keyless, but it runs on shared capacity. Fair-use limits apply so that no single caller can starve the rest of the community. This page explains what those limits look like from a client's perspective and when it's time to upgrade to a private tier.

Public (shared) fair use

Anonymous traffic to honeycluster.io is subject to a per-IP rate-limit ceiling. The exact numbers are tuned against real-world load and adjust over time — check the Pricing page for the current values.

When you exceed the ceiling, the edge proxy returns a standard 429 Too Many Requests response:


HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Rate limit exceeded, retry after 5 seconds"
}

A simple retry with exponential backoff handles transient spikes:

TypeScript
async function withRetry<T>(fn: () => Promise<Response>): Promise<T> {
  let delay = 500
  while (true) {
    const res = await fn()
    if (res.status !== 429) return res.json() as Promise<T>
    const retryAfter = Number(res.headers.get('retry-after') ?? Math.ceil(delay / 1000))
    await new Promise((r) => setTimeout(r, retryAfter * 1000))
    delay = Math.min(delay * 2, 30_000)
  }
}

For sustained traffic, upgrade to a private tier rather than relying on retries — the proxy won't queue shared-tier bursts indefinitely.

Private and enterprise plans

Private plans get their own rate-limit tier bound to an API key minted in the portal. Usage is metered in credits per request (cost varies by the work the backend does), and responses come back with per-request headers so you can monitor balance without polling a separate metrics endpoint.

Header	Meaning
`X-Credit-Cost`	Credits this request consumed
`X-Credits-Used`	Cumulative credits the project has consumed in the current window
`X-Credits-Remaining`	Credits left before the project hits its tier cap
`X-Credit-Exceeded`	`true` when the project has blown past its cap

A 1-credit lookup against a private endpoint looks like:


HTTP/1.1 200 OK
X-Credit-Cost: 1
X-Credits-Used: 842
X-Credits-Remaining: 99158
X-Credit-Exceeded: false
Content-Type: application/json

These headers only appear on authenticated traffic. Public shared-tier responses don't carry them — there's no per-caller bookkeeping because there's no key to bill against.

Throttling actions (private plans)

Each private tier defines a hard credit cap. When the cap is exceeded, the proxy can react in one of four ways — configured per project:

Action	Behavior
`allow`	Requests keep flowing, balance goes negative, overage is billed at cycle end
`warn`	Requests keep flowing, response headers include a `X-Credit-Warning`
`throttle`	Requests are queued briefly, then served — slower but not dropped
`block`	Proxy returns `429 Too Many Requests` with `Retry-After` until the window resets

block is the default for new projects.

Tuning cost

A few patterns that reduce load against both shared and private tiers:

•
Cache responses that don't change inside a single ledger. Historical ledger data is immutable, so it's safe to cache by ledger index.
•
Subscribe to WebSocket streams instead of polling. A 1-hour subscription costs less than 3,600 individual polls.
•
Batch multiple reads into a single JSON-RPC request where the underlying method supports it.
•
Filter upfront on the server side (request params) instead of fetching wide and filtering client-side.