Rate limits

Limits are enforced per API key at the gateway, by plan. Every RPC response carries live counters so your client can pace itself without guessing.

Plans

Plan	Requests/min	Requests/hour	Requests/day	Heavy methods/min	CU price (USD)
free	10	500	10,000	6	$0
standard	50	2,500	50,000	30	$0.001
premium	100	5,000	100,000	60	$0.0005
enterprise	1,000	50,000	1,000,000	600	$0.0002

Live source of truth — the plan catalog endpoint (JWT-authenticated, same login token as the rest of the management API):

curl https://api.nodes.koshelek.ru/api/v1/plans -H "Authorization: Bearer $TOKEN"

[
  {"tier":"free","per_minute":10,"per_hour":500,"per_day":10000,"price_per_cu":0},
  {"tier":"standard","per_minute":50,"per_hour":2500,"per_day":50000,"price_per_cu":0.001},
  {"tier":"premium","per_minute":100,"per_hour":5000,"per_day":100000,"price_per_cu":0.0005},
  {"tier":"enterprise","per_minute":1000,"per_hour":50000,"per_day":1000000,"price_per_cu":0.0002}
]

The endpoint returns the request-rate windows and the CU price; the heavy-method budget is enforced separately by the RPC proxy and isn't part of this payload.

Response headers

Every gateway response includes the current window state:

x-ratelimit-limit-minute: 1000
x-ratelimit-remaining-minute: 998
x-ratelimit-limit-hour: 50000
x-ratelimit-remaining-hour: 49998
x-ratelimit-limit-day: 1000000
x-ratelimit-remaining-day: 999998
ratelimit-limit: 1000
ratelimit-remaining: 998
ratelimit-reset: 23

ratelimit-reset is seconds until the tightest window resets.

When you exceed a limit — HTTP 429

{"message":"API rate limit exceeded"}

with a Retry-After: <seconds> header. Honor it — see Batches, retries & caching for a ready-made backoff snippet.

Heavy-method budgets by plan

Expensive scan/trace methods have a separate per-minute budget (the "Heavy methods/min" column above), counted per project across all chains. The heavy class covers trace_* methods plus:

• eth_getLogs (any EVM chain)
• eth_simulateV1, txpool_content
• qn_getTokenBalances
• debug_* — except on /eth, where they are blocked outright (HTTP 403, see below) and so never reach this budget.

The budget is a guardrail, not an exact meter

It is counted per proxy replica over a fixed one-minute window, so the effective ceiling can exceed the number above when traffic spreads across replicas — it exists to stop 100× abuse, not to bill you to the request. It also fails open: if the budget can't be read, your request is allowed rather than rejected.

Beyond the budget the request gets HTTP 429 + Retry-After with JSON-RPC error -32029:

{"jsonrpc":"2.0","error":{"code":-32029,"message":"heavy method rate limit exceeded for your plan, retry later"},"id":1}

Inside a batch the budget applies per item — over-budget items carry the -32029 error object while the rest of the batch executes.

Extra guard on /eth

On the Ethereum path specifically, eth_getLogs / eth_getFilterLogs are additionally clamped to 1 request/min per key, independent of plan:

// HTTP 429
{"message":"Heavy method rate limit: 1/min for eth_getLogs"}

debug_* methods on /eth are not available at all (HTTP 403, {"error":"debug methods not permitted"}) — they are rejected before any budget is consulted, so they are never merely throttled there.

Daily Compute-Unit quota

Independent of request-rate limits, each project has a daily CU budget (default 100,000 CU/day). Exhausting it returns JSON-RPC error -32005 (compute unit quota exceeded) on HTTP 200 — see Compute Units.

Usage warnings and abuse cool-downs

• The dashboard notifies you at 80 / 95 / 100 % of your plan's daily request allowance, and when the gateway has rejected a burst of your requests with 429s (usage.rate_limited_spike) — so a runaway client surfaces before it burns a day of quota.
• Sustained 429 storms can trigger a temporary automatic cool-down, where enabled: the key's limits are scaled down (typically to a quarter of the plan values) for a window (typically 1 hour), then restored automatically. It is a deployment-level safeguard that is off unless operators arm it — hammering 429s can also be a misconfigured-but-legitimate client. Well-behaved clients that back off per Retry-After never meet it either way.

Raising your limits

Two self-service paths, both reviewed by the operators:

• Dashboard — Billing → request a plan change; or open a support ticket with category limit_increase.
• API — one pending request per account at a time:

curl -X POST https://api.nodes.koshelek.ru/api/v1/limit-requests \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"requested_tier":"premium","reason":"launching indexer, need ~80 req/min sustained"}'

# check status (pending / approved / rejected)
curl https://api.nodes.koshelek.ru/api/v1/limit-requests -H "Authorization: Bearer $TOKEN"

A second POST while one is pending returns 409.

Suspended accounts — HTTP 402

If your tenant is suspended (e.g. unpaid invoices), every RPC request returns HTTP 402:

{"message":"account suspended — contact your administrator"}

Keys are preserved; service resumes the moment the account is reactivated — see Billing.