Error Reference | BlockVectra Docs

BlockVectra error codes, billing and retry guidance for JSON-RPC, Data API, Push Webhooks, console and faucet, including eth_getLogs block ranges and Webhook replay errors.

This reference documents all error codes and machine-readable reason values across BlockVectra services, including whether a rejected call is billed, retry policies, backoff durations, and recommended actions for AI agents and automated clients.

For machine-readable consumption, fetch the complete catalog as JSON at /errors.json. Every error response carrying a docs_url links directly to a stable anchor on this page: https://docs.blockvectra.com/en/errors/#<reason> (or #-<code-number> for errors without a reason code).

JSON-RPC errors

HTTP	Code	Reason	Meaning	Billed	Retryable	Wait Time (Retry-After)	Agent Action
401	-32024	`missing_api_key`	missing API key: send it in the request path (/v1/{chain}/<api_key>) or in the x-api-key header	No	No	—	For JSON-RPC endpoints (/v1/{chain}), provide API key in request path (/v1/{chain}/<api_key>) or in x-api-key header. For Data API (/v1/data/) and Top-up API (/v1/topup/), provide API key only in x-api-key header.
401	-32024	`invalid_api_key`	Unknown, disabled, or revoked API key: JSON-RPC and Data API both return HTTP 401 with an invalid_api_key error envelope (JSON-RPC: error.code -32024 and error.data.reason invalid_api_key; Data API: error.code and error.data.reason invalid_api_key).	No	No	—	Check the API key; if necessary, sign in again in the console or via programmatic sign-up to create a new key (see Lost your session or API key?).
403	-32025	`key_expired`	API key expired; create a new key in the console	No	No	—	API key expired; create a new key in the console or via programmatic sign-up.
403	-32025	`key_cap_exhausted`	API key CU cap exhausted; create a new key in the console	No	No	—	API key lifetime CU cap used up; create a new key in the console or via programmatic sign-up.
503	-32021	`auth_unavailable`	authentication data temporarily unavailable	No	Yes	Honor Retry-After header (seconds)	Server is temporarily unable to verify keys; this is not an issue with your key. Retry after waiting per Retry-After; do not recreate the key.
404	-32600	`unknown_chain`	unknown chain	No	No	—	Check available chains via GET /v1/chains or the list_chains tool; verify URL path.
404	unknown_endpoint	`unknown_endpoint`	Data API method and path do not match a known operation	No	No	—	Verify method and URL path against Data API documentation.
200	-32700	`parse_error`	parse error	No	No	—	Verify valid JSON syntax in request body before sending.
200	-32600	`invalid_request`	invalid request	No	No	—	Inspect request structure; verify jsonrpc: '2.0', id, and method fields before resending.
200	-32602	`invalid_params`	tracer not allowed	No	No	—	Adjust method params; check supported tracers and timeout limits for the chain.
200	-32602	`logs_range_too_large`	eth_getLogs block range too large: max <N> blocks	No	No	—	Narrow query block range to within max_logs_block_range indicated in GET /v1/chains.
429	-32005	`public_rate_limit`	public request rate limit exceeded	No	Yes	Honor Retry-After header (seconds)	Wait for the Retry-After header, then retry; or send the request with an API key (get one).
429	-32005	`public_pool_busy`	public chain pool is busy	No	Yes	Honor Retry-After header or wait a few seconds and retry with backoff	Retry with backoff, or send the request with an API key (get one).
200	-32601	`method_not_public`	Method is not available on the public endpoint	No	No	—	Use a method the public endpoint supports, or send the request with an API key (get one).
200	-32601	`method_not_allowed`	Method is not available on this chain or has been disabled by policy	No	No	—	Check methods.allow and methods.deny in GET /v1/chains for supported methods. Transaction sending support is determined by methods.allow in GET /v1/chains.
200	-32601	`subscription_not_available`	WebSocket subscription is not offered on this chain	No	No	—	Check available subscriptions for this chain via GET /v1/chains.
200	-32602	`logs_filter_required`	logs subscription requires an address or topic0 (a non-null value in the first topics position)	No	No	—	Specify an address or a non-null topic0 in the logs filter.
200	-32600	`batch_too_large`	batch too large: max <N> calls	No	No	—	Split batch into smaller batches meeting the max call limit indicated in error data.
413	request_too_large	`request_too_large`	Data API request body exceeds the size limit	No	No	—	Reduce request body size.
200	-32000	`not_found`	transaction not found	No	No	—	If newly submitted or mined, wait for propagation and retry; otherwise check block number or hash.
200	-32011	`state_window`	historical state is not available beyond the most recent <N> blocks	No	No	—	Query blocks within state_window_blocks as reported in GET /v1/chains, or use Data API for historical data.
200	-32011	`range_not_indexed`	requested history is not completely indexed	No	No	—	Narrow the requested history to an indexed range; do not retry the same uncovered range unchanged.
200	-32011	`history_not_ready`	requested history is not ready	No	Yes	Wait for indexing to catch up; honor error.data.retry_after_seconds when present	Retry after indexing catches up, waiting error.data.retry_after_seconds when provided.
429	-32005	`key_rate_limit`	rate limit exceeded	No	Yes	Honor Retry-After header (seconds)	Sleep for the duration specified in Retry-After header before retrying, or distribute load.
429	rate_limited	`rate_limited`	Request rate limit exceeded on API or GET /v1/account (more than 5 requests per second for this key)	No	Yes	Honor Retry-After header (seconds)	Sleep for duration in Retry-After before retrying.
429	-32005	`concurrency_limit`	rate limit exceeded	No	Yes	Honor Retry-After header or wait for active calls to complete	Limit client concurrency pool size and retry completed slots.
429	-32005	`free_plan_call_limit`	rate limit exceeded	No	Yes	Wait 1 second before retrying	Throttle request rate or top up to unlock paid tier throughput.
429	-32022	`request_exceeds_burst`	request cost <N> CU exceeds burst capacity <M> CU	No	No	—	Waiting will not succeed; split batch or lower method parameters to fit within burst capacity.
429	-32022	`free_plan_batch_too_large`	request has <N> calls, exceeding the free-plan limit of <M> calls per second	No	No	—	Waiting will not succeed; split batch so call count is within free-plan limit, or top up.
429	-32005	`ws_connection_limit`	WebSocket connection limit reached for this key or account	No	No	—	Close an unused WebSocket connection or reuse an existing connection.
200	-32022	`subscription_limit`	WebSocket subscription limit reached for this connection	No	No	—	Unsubscribe an existing subscription or open another connection.
200	-32005	`ws_filter_capacity`	WebSocket logs filters are at capacity	No	No	—	Unsubscribe an existing logs subscription or use a narrower filter.
200	-32026	`ws_push_overloaded`	WebSocket notification queue is overloaded	No	Yes	Retry later with backoff, or reconnect	Retry eth_subscribe with exponential backoff, or reconnect. Existing subscriptions continue receiving notifications.
200	-32005	`overloaded`	service overloaded, retry later	No	Yes	Wait a few seconds and retry with exponential backoff	Back off with jitter and retry request.
402	-32020	`balance_exhausted`	Insufficient balance (when balance is known, error.data includes balance_units and balance_cu)	No	No	—	Top up on-chain: get your deposit address from the Console or `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); see the agent top-up guide, or use quota reset in console if eligible. When balance is known, error.data carries balance_units (negative when overdrawn) and balance_cu.
402	-32020	`free_grant_exhausted`	Free grant exhausted (when balance is known, error.data includes balance_units and balance_cu)	No	No	—	Top up on-chain: get your deposit address from the Console or `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); see the agent top-up guide, use quota reset if available, or wait for next cycle grant. When balance is known, error.data carries balance_units (negative when overdrawn) and balance_cu.
503	-32021	`billing_unavailable`	billing data temporarily unavailable	No	Yes	Honor Retry-After header (seconds)	This is not a balance issue; newly created keys sync within seconds. Wait for Retry-After and retry.
200	-32010	`node_syncing`	node is syncing; calls are temporarily unavailable	No	Yes	Wait a few seconds and retry	Wait for node synchronization to finish, or check GET /v1/status.
200	-32603	`upstream_unavailable`	upstream unavailable	No	Yes	Wait a few seconds and retry	Retry with exponential backoff; check GET /v1/status for node health.
504	504	`upstream_timeout`	Upstream service did not answer within the time limit	No	Yes	Retry after a brief delay	Retry the request with exponential backoff.
200	-32000	`response_too_large`	upstream response too large	No	No	—	Narrow query parameters (e.g. reduce block range in eth_getLogs or request smaller traces).
200	-32603	`internal_error`	internal service error	No	No	—	Retry request; report persistent failures with timestamp to support.
200	4444	—	pruned history unavailable	No	No	—	Block is outside the node's pruned history window; query historical blocks via Data API.
200	-32000	—	historical state ... is not available; old data not available due to pruning...; missing trie node ...	No	No	—	Query blocks within the state window, or use Data API for historical queries.
200	-32002	—	<node message>	No	Yes	Wait a few seconds and retry with a smaller batch	Reduce the number of calls in the batch and retry.
200	-32003	—	<node message>	No	No	—	Split batch into smaller requests to reduce response payload size.
200	-32601	—	<node message>	No	No	—	Check methods.allow and methods.deny in GET /v1/chains for supported methods. Transaction sending support is determined by methods.allow in GET /v1/chains.
200	-32603	—	<node message>	No	Yes	Retry after a brief delay	Retry request; report persistent failures with timestamp to support.
200	-32600	—	<node message>	No	No	—	Inspect individual requests in the batch for non-compliant parameters; split and retry.
200	*	—	<node message>	Yes	No	—	Node performed computation and was billed. Inspect revert reason/data or call parameters; do not blindly retry.
408	408	—	Request timed out after 35s between request header completion and response	Possible	Yes	Wait a few seconds before retrying read calls	Calls may have reached node and could be billed. For read calls, retry with backoff. For write calls (e.g. eth_sendRawTransaction), check transaction status by hash first.

WebSocket Close Codes

WebSocket connection close codes and recommended client actions.

Code	Reason	Meaning	Retryable	Wait Time (Retry-After)	Agent Action
1001	—	idle	Yes	Reconnect as needed	Reconnect as needed.
1003	—	binary frames are not accepted	No	—	Do not reconnect automatically; send UTF-8 text frames only.
1009	—	message too large	No	—	Do not reconnect automatically; split large requests to stay under 1 MiB.
1012	—	service restart	Yes	Reconnect with jittered backoff	Reconnect with jittered backoff, re-subscribe, and backfill missed data.
1013	—	chain unavailable; overloaded	Yes	Reconnect with exponential full-jitter backoff	Reconnect with exponential full-jitter backoff, re-subscribe, and backfill missed data.
4402	—	insufficient balance	No	—	Do not reconnect automatically; top up on-chain: get your deposit address from the Console or `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); see the agent top-up guide, or use quota reset in console if eligible.
4404	—	invalid api key	No	—	Do not reconnect automatically; verify or rotate API key in console.
4408	—	The service closes a session whose push queue passes 512 KiB (524,288 bytes) and drops pending notifications; clients may not receive a close frame (browser reports 1006); treat unexpected disconnects like 4408.	Yes	Reconnect with backoff; subscribe to less or read faster	Clients should treat an unexpected drop (no close frame received, browser reports 1006) like 4408: reconnect with backoff, re-establish subscriptions, and backfill dropped data with eth_getLogs; subscribe to less, or read faster.
4429	—	push rate exceeded	Yes	Reconnect with backoff or reduce subscriptions	Reduce subscriptions or reconnect with backoff.
4503	—	billing unavailable	Yes	Reconnect with exponential full-jitter backoff	Reconnect with exponential full-jitter backoff and re-subscribe.

Data API Errors

Errors returned by the Blockchain Data API endpoints under /v1/data/{chain}/.

HTTP	Code	Reason	Meaning	Billed	Retryable	Wait Time (Retry-After)	Agent Action
400	bad_request	—	Duplicate query parameter, invalid query string, or malformed request	No	No	—	Inspect query parameters; ensure parameters like limit appear at most once and query parameters are valid.
409	not_indexed_yet	—	Requested block number or window is above as_of_block, or hash resolves above as_of_block (carries indexed_through unless chain has no indexed blocks)	No	Yes	Wait a few seconds until indexed_through reaches the block	Poll until the requested block or to_block is at or below indexed_through, or wait for the chain to start writing blocks.
409	window_too_large	—	Block window spans more than 100,000 blocks and clamp parameter was not set to true	No	No	—	Narrow block range (from_block to to_block) <= 100,000 blocks, or pass clamp=true.
409	too_many_pools	—	Token matches more than 200 liquidity pools; query by pool dimension instead	No	No	—	Query by specific pool address rather than querying all pools for the token.
409	span_exceeded	—	Requested date span exceeds the 90-day maximum limit	No	No	—	Narrow date range between from_time and to_time to within 90 days.
422	no_coverage	—	Capability not supported on this chain, or requested block is before the coverage window	No	No	—	Check `features` and `coverage.from_block` in GET /v1/data/chains (or `data_features` in the free GET /v1/status) before querying.
503	unavailable	—	Data service temporarily unavailable	No	Yes	Wait a few seconds and retry with exponential backoff	Retry after a brief delay with exponential backoff.
402	insufficient_balance	—	Paid balance or free grant exhausted (when balance is known, error.data includes balance_units and balance_cu)	No	No	—	Top up on-chain: get your deposit address from the Console or `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); see the agent top-up guide, or wait for the free allowance to refill.
429	cost_exceeds_burst	—	A single request costs more than the key's burst capacity	No	No	—	Split the request into smaller ones; retrying it as sent never succeeds.
503	gateway_overloaded	—	Data API capacity is temporarily unavailable	No	Yes	Retry-After: 1 second	Reduce concurrent requests across this account's keys and chains; wait Retry-After before retrying. error.data.reason is null.

Console, Account & Faucet API Errors

Errors returned by the management, key provisioning, authentication, and faucet endpoints under /v1/.

HTTP	Code	Reason	Meaning	Billed	Retryable	Wait Time (Retry-After)	Agent Action
409	topup_disabled	—	Top-up paused or no available networks for top-up at this time; new addresses cannot be allocated, but existing allocated addresses remain assigned to the account	No	No	—	Check top-up availability via GET /v1/topup/status; retry later when top-up is enabled.
503	deposit_unavailable	—	Unable to allocate a deposit address temporarily; retry per Retry-After header	No	Yes	Honor Retry-After header (seconds) and use exponential backoff	Retry per the Retry-After header with exponential backoff.
400	invalid_request	`invalid_username`	Username exceeds 64 Unicode characters after trimming, or contains a control character (Cc) or lone surrogate (Cs)	No	No	—	Surrounding whitespace is trimmed, and an empty result is treated as null. Otherwise use at most 64 Unicode characters without control characters (Cc) or lone surrogates (Cs).
400	invalid_request	`expires_at`	Key expiration time is not in the future or exceeds the maximum allowed key validity period	No	No	—	Set expires_at to a future RFC 3339 timestamp within the allowed validity period (default 365 days), or use expires_in_secs.
400	invalid_request	`cu_cap`	The cu_cap parameter is out of bounds (must be an integer between 1 and 9007199254740991)	No	No	—	Adjust cu_cap to be an integer between 1 and 9007199254740991 or omit it for unlimited CU.
400	siwe_invalid	`expired`	Sign-In with Ethereum (SIWE) message has expired or nonce was already used	No	Yes	Fetch a new challenge immediately and sign	Request a fresh challenge from /v1/auth/siwe/challenge and sign the newly issued statement.
400	siwe_invalid	`chain_mismatch`	SIWE message chainId does not match server settings	No	No	—	Use the chainId returned by /v1/auth/siwe/challenge when constructing the SIWE message.
400	siwe_invalid	`domain_mismatch`	SIWE message domain does not match server host	No	No	—	Ensure domain and uri match the server host returned in challenge.
400	siwe_invalid	`signature`	SIWE cryptographic signature verification failed	No	No	—	Verify that the message was signed by the private key corresponding to the specified address.
409	key_limit_reached	`active_keys`	Unrevoked, unexpired API keys (including disabled keys) reached maximum account limit	No	No	—	Revoke an existing unused key before creating a new key.
409	no_reset_available	`nothing_to_reset`	Balance is already at or above the reset target; reset opportunity is preserved	No	No	—	No reset needed currently; use reset opportunity after balance is depleted.
429	rate_limited	`daily_creations`	Account 24-hour key creation limit reached	No	Yes	Honor Retry-After header (seconds)	Honor Retry-After and wait for creation quota to become available; rotation uses the same quota.
429	signup_rate_limited	`per_ip`	Sign-up rate limit reached for the client IP subnet	No	Yes	Honor Retry-After header (seconds)	Wait for the Retry-After interval before creating a new account from this network.
429	signup_rate_limited	`global`	Global new user registration rate limit reached across all sources	No	Yes	Honor Retry-After header (seconds)	Wait for the Retry-After interval before retrying account creation.
400	oauth_invalid	—	OAuth parameter invalid or callback state unknown, expired, or already used	No	Yes	—	Initiate a fresh OAuth login flow from /v1/auth/{provider}/start.
400	login_code_invalid	—	Login code unknown, expired, already consumed, or PKCE verifier mismatch	No	No	—	Restart login to obtain a fresh login code.
401	unauthenticated	—	Missing session, or session token is invalid, expired, or revoked; on top-up API (/v1/topup/*), this also occurs when Authorization header contains a non-Bearer or invalid token instead of x-api-key	No	No	—	Sign in again to acquire a new Bearer session token; on top-up API, use x-api-key request header instead of Authorization header to pass API key.
403	user_disabled	—	Account has been suspended by administration	No	No	—	Contact contact@blockvectra.com for account support.
404	provider_disabled	—	OAuth provider is recognized but currently disabled	No	No	—	Use SIWE or another supported authentication provider.
409	identity_in_use	—	Identity (wallet or OAuth account) is already bound to another user	No	No	—	Unbind the identity from the previous account or use a different identity.
409	identity_limit_reached	—	Maximum number of linked identities (5) reached for this account	No	No	—	Unbind an unnecessary identity before linking a new one.
409	last_identity	—	Cannot unbind the sole remaining identity from the account	No	No	—	Bind another identity first before removing this one.
409	key_not_active	—	Attempted to rotate an API key that is disabled, revoked, or expired	No	No	—	Create a new key or rotate an active key.
409	no_reset_available	—	No quota reset opportunities remain on this account	No	No	—	Top up on-chain: get your deposit address from the Console or `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); see the agent top-up guide, or wait for the next promotion cycle.
413	payload_too_large	—	Request body exceeds the 64 KiB size limit	No	No	—	Reduce request body size below 64 KiB.
503	signup_paused	—	Global new user registrations are temporarily paused; existing logins unaffected	No	Yes	Retry registration later	New user sign-ups temporarily paused; check status and try again later.
503	usage_unavailable	—	Usage reporting service is temporarily unavailable	No	Yes	Wait a few seconds and retry	Only affects /usage endpoint; other endpoints work normally. Retry shortly.
500	internal	—	Unexpected server error	No	Yes	Retry after a brief delay	Retry request with exponential backoff.
400	invalid_address	`invalid_address`	Recipient address format or checksum is invalid	No	No	—	Use 0x followed by 40 hexadecimal characters, lowercase or EIP-55 checksummed; check data.field (/address).
503	faucet_empty	`faucet_empty`	The faucet has insufficient funds for the claim and transaction fee	No	Yes	Honor Retry-After header (seconds)	Wait for Retry-After before retrying; do not assume test ETH has been sent without an accepted response.
503	service_unavailable	`service_unavailable`	Faucet claim processing is temporarily unavailable, or a previous claim has no receipt yet	No	Yes	Honor Retry-After header (seconds)	Wait for Retry-After before retrying; do not assume test ETH has been sent without an accepted response.

Push API Errors

Errors from webhook subscription management and event history under /v1/push/.

HTTP	Code	Reason	Meaning	Billed	Retryable	Wait Time (Retry-After)	Agent Action
400	invalid_request	—	Invalid request fields, addresses, pagination or block range.	No	No	—	Inspect data.field and data.invalid; correct the request.
401	missing_api_key	—	Missing x-api-key.	No	No	—	Supply your API key in x-api-key.
401	invalid_api_key	—	Unknown, disabled or revoked API key.	No	No	—	Use an active key from your account.
402	insufficient_balance	—	Balance or free allowance exhausted for event history.	No	No	—	Inspect data.reason (balance_exhausted or free_grant_exhausted) and data.balance_units / data.balance_cu when present; top up via data.topup_url or data.deposit_address_url.
403	key_cap_exhausted	—	API key CU cap exhausted for event history.	No	No	—	Inspect data.cu_cap and create a new key in the console.
403	key_expired	—	API key has expired.	No	No	—	Use an unexpired key from your account.
404	not_found	—	Route, method or subscription not found.	No	No	—	Check the path, method and subscription ownership.
409	limit_reached	—	Account subscription or address-pair limit reached.	No	No	—	Inspect data.limit and data.max; reduce subscriptions or addresses.
413	request_too_large	—	Request body exceeds the route limit.	No	No	—	Split the address batch or reduce the body size.
422	chain_not_available	—	Chain unavailable for push or absent from the subscription.	No	No	—	Check GET /v1/push/chains and the subscription chains.
422	chains_required	—	At least one chain is required.	No	No	—	Provide a nonempty chains object; use offline status to stop listening.
422	confirmations_out_of_range	—	Confirmation depth outside the chain range.	No	No	—	Choose confirmations within data.min and data.max.
422	destination_not_allowed	—	Receiving URL is not allowed.	No	No	—	Inspect data.rule; use an HTTPS hostname on port 443 without userinfo or fragment.
422	block_out_of_range	—	Block range outside available replay or history coverage.	No	No	—	Use data.min_block and data.max_block to adjust the range.
429	cost_exceeds_burst	—	History request cost exceeds key burst capacity.	No	No	—	Inspect data.reason (request_exceeds_burst) and data.max; increase burst capacity before retrying. Retrying unchanged does not help.
429	rate_limited	—	Management or history query rate limit reached.	No	Yes	Wait the seconds in Retry-After.	For history, inspect data.reason (key_rate_limit or free_plan_call_limit); wait Retry-After seconds and reduce request frequency or concurrency.
500	internal_error	—	Unexpected service error.	No	No	—	Keep x-bv-request-id and contact support.
503	auth_unavailable	—	API key validation temporarily unavailable.	No	Yes	Wait the seconds in Retry-After.	Wait Retry-After seconds before retrying.
503	billing_unavailable	—	History billing state temporarily unavailable.	No	Yes	Wait the seconds in Retry-After.	Wait Retry-After seconds before retrying.
503	upstream_unavailable	—	Push service temporarily unreachable.	No	Yes	Wait the seconds in Retry-After.	Wait Retry-After seconds before retrying.
503	service_unavailable	—	Push service or address capacity temporarily unavailable.	No	Yes	Wait the seconds in Retry-After.	Wait Retry-After seconds before retrying.

For Webhook subscription or replay errors, follow the Push delivery recovery guide. Receiver integration starts with raw-body signature verification; the stablecoin payment example adds event deduplication, receipt checks, gap backfill and reorg reconciliation. See billing rules for metering and WebSocket reconnection for connection-based subscriptions.

For logs_range_too_large, check the eth_getLogs method parameters and follow the block range limit and chunked queries guide.

For faucet claims on Robinhood Chain, see the testnet faucet guide for eligibility and handling of shared error codes.

When debugging parameter encoding for eth_estimateGas or eth_call, encode Quantity and Data as described in EIP-1474 value encoding: do not use JavaScript Number for large integers, never catch an encoding failure and default it to zero, and read the actual returned code, reason and HTTP status before classifying it — invalid params is not automatically a slippage or retry/backoff condition.