Limits, credits and errors
1 credit = 1 request on every chain, with three weights. What each plan allows and what every error means.
Contents
Chains, regions and plans open one by one when enough teams ask for them. These docs describe exactly how they work. What is open
Limits per plan
Per account: all tokens and chains share the numbers. Each call of a batch counts as one request.
| Plan | Credits / month | Requests / s | Burst | Tokens | Trace, debug | Above the credits |
|---|---|---|---|---|---|---|
| Free $0 | 1M | 10 | 20 | 1 | No | Requests answer 429 until the 1st |
| Starter $49 | 10M | 50 | 100 | 5 | Yes | Optional overage, $5 per 1M, with your monthly cap |
| Growth $249 | 60M | 200 | 400 | 20 | Yes | Optional overage, $4 per 1M, with your monthly cap |
| Scale $799 | 250M | 500 | 1,000 | 50 | Yes | Optional overage, $3 per 1M, with your monthly cap |
| Enterprise from $2,500 | from 1B | by contract | - | 100 | Yes | By contract |
- Requests per second is a token bucket: short bursts up to twice the rate, then the plan rate. Above it: HTTP 429
rate_limitedwithRetry-After. - Free also has a limit per client network, so one shared address cannot use up a whole region.
- Credits reset on the 1st of each month (UTC). Overage is off until you switch it on, always with a cap you set. E-mails at 80 % and 100 %.
- Body and batch: at most 256 KB per request and 100 calls per batch. A batch can never be larger than your burst (Free: 20 calls), so split bigger ones.
- Dedicated throughput works differently: a sustained rate of 25, 100, 250 or 500 requests per second on one chain in one region, with no credits and no overage. Above the rate: HTTP 429. Prices on RPC pricing.
Credits and weights
Every chain counts the same. What the gateway refuses and what fails on our side costs nothing; an answer from the chain costs its weight, also a revert, also from the cache.
Answered by the gateway Weight 0
eth_chainId and net_version come straight from the gateway: no node call, no credits.
eth_chainIdnet_version
Standard reads Weight 1
web3_clientVersionweb3_sha3net_listeningnet_peerCounteth_blockNumbereth_syncingeth_protocolVersioneth_gasPriceeth_maxPriorityFeePerGaseth_feeHistoryeth_blobBaseFeeeth_getBalanceeth_getCodeeth_getStorageAteth_getTransactionCounteth_getProofeth_calleth_estimateGaseth_createAccessListeth_simulateV1eth_getBlockByHasheth_getBlockByNumbereth_getBlockTransactionCountByHasheth_getBlockTransactionCountByNumbereth_getUncleByBlockHashAndIndexeth_getUncleByBlockNumberAndIndexeth_getUncleCountByBlockHasheth_getUncleCountByBlockNumbereth_getTransactionByHasheth_getTransactionByBlockHashAndIndexeth_getTransactionByBlockNumberAndIndexeth_getTransactionReceipt
Heavy reads Weight 2
Full-transaction blocks (eth_getBlockByNumber or eth_getBlockByHash with true) also count as heavy.
eth_getLogseth_getBlockReceiptstrace_transactiontrace_get
Trace and debug Weight 5
Paid plans only (Starter and up). On Free these calls answer plan_required.
trace_blocktrace_calltrace_callManytrace_filtertrace_rawTransactiontrace_replayBlockTransactionstrace_replayTransactiondebug_traceTransactiondebug_traceCalldebug_traceBlockByNumberdebug_traceBlockByHashdebug_getRawBlockdebug_getRawHeaderdebug_getRawReceiptsdebug_getRawTransaction
Transaction submission Weight 1
Not enabled yet: Blockmetric RPC is read-only during the beta (tx_submit_disabled).
eth_sendRawTransactioneth_sendRawTransactionConditionaleth_sendRawTransactionSync
Subscriptions (WebSocket only) Weight 1 per call, notifications 1 per started 4 KB
newHeads and logs. newPendingTransactions (mempool) is not offered.
eth_subscribeeth_unsubscribe
HyperCore info types weigh 1, 2 or 5 by the size of their answer: see HyperCore. Chain-specific extras (HyperEVM) are standard reads.
Not offered
These answer method_not_allowed and cost nothing.
| Methods | Why |
|---|---|
eth_sendTransaction | The gateway holds no keys: sign locally and send the raw transaction. |
eth_sign, eth_signTransaction, eth_signTypedData | The gateway holds no keys: signing is not offered. |
eth_accounts, eth_requestAccounts | The gateway holds no accounts. |
eth_coinbase, eth_mining, eth_hashrate, eth_submitWork, eth_submitHashrate | Not offered on a shared endpoint. |
eth_newFilter | Stateful filters are not offered (requests may reach different nodes): use eth_getLogs, or eth_subscribe over WebSocket. |
eth_newBlockFilter | Stateful filters are not offered: use eth_subscribe("newHeads") over WebSocket. |
eth_newPendingTransactionFilter, txpool_* | Mempool access is not offered. |
eth_getFilterChanges, eth_getFilterLogs | Stateful filters are not offered: use eth_getLogs with a block range. |
eth_uninstallFilter | Stateful filters are not offered. |
personal_* | Account and signing methods are not offered. |
admin_*, miner_* | Node administration is not offered. |
engine_* | The engine API is not offered. |
debug_* | Only the read-only debug_trace* and debug_getRaw* methods are offered. |
clique_*, parity_* | Not offered. |
Response headers
X-Blockmetric-Credits | Credits this request cost (the sum over a batch). |
|---|---|
X-Blockmetric-Credits-Remaining | Credits left this month before overage or the limit. |
X-Blockmetric-Overage | "on" while your monthly credits are used up and overage (within your cap) pays for the calls. |
X-RateLimit-Limit | Requests per second of your plan. |
X-RateLimit-Remaining | Requests left in the current burst. |
X-RateLimit-Reset | Unix time (seconds) when the bucket refills. |
Retry-After | On 429 and 503 when waiting helps: seconds to wait before the next try. |
X-Request-Id | Quote it when you contact support. |
X-Blockmetric-Chain | The chain that answered. |
Errors
Every error is a JSON-RPC error with data.code, data.doc_url and data.request_id. Errors of single calls in a batch come back in their slot with HTTP 200. Errors from the chain itself (a revert) are passed through as the node sent them, only node addresses are removed.
| data.code | JSON-RPC | HTTP | Meaning |
|---|---|---|---|
parse_error | -32700 | 400 | The body is not valid JSON. |
invalid_request | -32600 | 400 | Not a JSON-RPC 2.0 request (missing "jsonrpc": "2.0", "method" or a bad "id"). |
batch_too_large | -32600 | 400 | More calls in one batch than allowed (100). Split the batch. A batch above your burst (twice your requests per second) answers rate_limited. |
payload_too_large | -32600 | 413 | The body is larger than 256 KB (HyperCore info requests: 16 KB). |
upgrade_required | -32600 | 426 | A GET without a WebSocket upgrade. Send JSON-RPC with POST over HTTPS, or connect with a WebSocket client. |
https_required | -32600 | 403 | The request came over plain http. Only https is accepted; rotate a token that was sent unencrypted. |
key_in_url | -32600 | 400 | A Blockmetric API key (bm_live_…) or a credential query parameter was in the URL. Only endpoint tokens (bmr_…) may be in the path. Revoke a key that was in a URL. |
unauthorized | -32001 | 401 | The endpoint token is missing, mistyped, revoked or unknown. |
chain_not_allowed | -32002 | 403 | The token is restricted to other chains. Change its chains on the dashboard. |
origin_not_allowed | -32002 | 403 | The browser origin is not on the token's list of allowed origins. |
ip_not_allowed | -32002 | 403 | The client address is not on the token's IP allowlist. |
region_blocked | -32002 | 451 | Not available in this country or region (sanctions). |
chain_not_open | -32002 | 403 | The Global plans do not serve this chain yet. Join the waitlist for it on its chain page; we open chains when enough teams ask for them. |
region_not_open | -32002 | 403 | This region does not serve the Global plans yet. Use the global endpoint, or join the waitlist for the region. |
region_not_served | -32002 | 403 | A dedicated endpoint is served in one region only. Use the endpoint URL of its region from the dashboard. |
rate_limited | -32005 | 429 | More requests per second than the plan allows (each call of a batch counts), too many concurrent requests with one token, or too many requests with invalid tokens from one network. Retry after the Retry-After header. A batch larger than the burst never passes: split it. |
quota_exceeded | -32005 | 429 | The monthly credits are used up and overage is off (or its cap is reached). Resets on the 1st (UTC). |
ws_limit | -32005 | 429 | More open WebSocket connections than the plan allows. |
method_not_found | -32601 | 200, per call | The method does not exist on this chain. |
method_not_allowed | -32004 | 200, per call | The method is not offered (signing, accounts, admin, mempool, stateful filters). |
plan_required | -32004 | 200, per call | Trace and debug methods of weight 5 are part of the paid plans (trace_transaction and trace_get are heavy reads on every plan). |
tx_submit_disabled | -32004 | 200, per call | Sending transactions is not enabled yet: read-only during the beta. |
websocket_required | -32004 | 200, per call | eth_subscribe needs a WebSocket connection. |
invalid_params | -32602 | 200, per call | A parameter failed our checks (e.g. more than 4 topics or 16 addresses in a log filter). |
block_range_too_large | -32602 | 200, per call | eth_getLogs spans more blocks than allowed on this chain (10,000; HyperEVM 50), or trace_filter more than 100 blocks. Page through smaller ranges. |
auth_unavailable | -32603 | 503 | Token verification is briefly unavailable on our side. Retry after the Retry-After header. |
upstream_unavailable | -32010 | 503 | No healthy node for this chain right now. Retry with backoff; /<chain>/health shows the state. |
upstream_busy | -32010 | 503 | Capacity for this chain is used up for a moment. Retry after the Retry-After header. |
upstream_error | -32011 | 502 | The node returned something that is not a JSON-RPC answer. Retry. |
not_found | -32601 | 404 | Unknown chain or path. Use /<chain>/<token> with a chain from the list. |
None of these costs credits.
Code snippets in these docs are licensed under MIT-0: copy them into your own code without attribution. Use of Blockmetric RPC is governed by the terms. Independent infrastructure, not affiliated with the chains or their foundations.