Error Reference

Complete reference for BlockVectra JSON-RPC, Data API, and console error codes, reasons, billing rules, retry guidance, and agent actions.

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).

Special Empty Responses

HTTP 404 (Empty Body): Invalid, Suspended, or Revoked API Key

When a request to /v1/{chain} has no API key, or the key is unrecognized, disabled, or revoked, the service returns HTTP 404 with an empty body. For security and anti-probing reasons, the service intentionally does not distinguish between these cases. Agent action: Ensure a valid API key is passed via the x-api-key header or configured in the BLOCKVECTRA_API_KEY environment variable.

HTTP 403 (Empty Body): Non-POST Method on JSON-RPC Endpoints

When a request to /v1/{chain} or /v1/{chain}/{api_key} uses an HTTP method other than POST or OPTIONS (e.g. GET), the service returns HTTP 403 with an empty body and an Allow: POST,OPTIONS header. Agent action: Always use the POST method for JSON-RPC requests.

JSON-RPC errors

Errors returned during JSON-RPC dispatch, upstream node forwarding, or service admission control.

HTTP	Code	Reason	Meaning	Billed	Retryable	Wait Time (Retry-After)	Agent Action	Related Doc	Anchor
200	-32700	`parse_error`	parse error	No	No	—	Verify valid JSON syntax in request body before sending.	JSON-RPC Docs	#parse_error
200	-32600	`invalid_request`	invalid request	No	No	—	Inspect request structure; verify jsonrpc: '2.0', id, and method fields before resending.	JSON-RPC Docs	#invalid_request
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.	JSON-RPC Docs	#batch_too_large
200	-32601	`method_not_allowed`	method not available: <method>	No	No	—	Check methods.allow and methods.deny in GET /v1/chains for supported methods.	JSON-RPC Docs	#method_not_allowed
404	-32600	`unknown_chain`	unknown chain	No	No	—	Check available chains via GET /v1/chains or the list_chains tool; verify URL path.	JSON-RPC Docs	#unknown_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.	JSON-RPC Docs	#logs_range_too_large
200	-32602	`invalid_params`	tracer not allowed	No	No	—	Adjust method params; check supported tracers and timeout limits for the chain.	JSON-RPC Docs	#invalid_params
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.	JSON-RPC Docs	#node_syncing
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.	JSON-RPC Docs	#state_window
200	-32000	`not_found`	transaction not found	No	Yes	Retry after a few seconds if recently broadcast or mined	If newly submitted or mined, wait for propagation and retry; otherwise check block number or hash.	JSON-RPC Docs	#not_found
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).	JSON-RPC Docs	#response_too_large
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.	JSON-RPC Docs	#overloaded
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.	JSON-RPC Docs	#key_rate_limit
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.	JSON-RPC Docs	#free_plan_call_limit
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.	JSON-RPC Docs	#concurrency_limit
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.	JSON-RPC Docs	#request_exceeds_burst
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.	JSON-RPC Docs	#free_plan_batch_too_large
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.	JSON-RPC Docs	#upstream_unavailable
200	-32603	`internal_error`	internal service error	No	Yes	Retry after a brief delay	Retry request; report persistent failures with timestamp to support.	JSON-RPC Docs	#internal_error
402	-32020	`balance_exhausted`	insufficient balance	No	No	—	Contact contact@blockvectra.com to top up, or use quota reset in console if eligible.	JSON-RPC Docs	#balance_exhausted
402	-32020	`free_grant_exhausted`	insufficient balance	No	No	—	Contact contact@blockvectra.com to top up, use quota reset if available, or wait for next cycle grant.	JSON-RPC Docs	#free_grant_exhausted
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	—	Provide a valid API key in request path (/v1/{chain}/<api_key>) or in x-api-key request header.	JSON-RPC Docs	#missing_api_key
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.	JSON-RPC Docs	#billing_unavailable
200	4444	—	pruned history unavailable	No	No	—	Block is outside the node's pruned history window; query historical blocks via Data API.	JSON-RPC Docs	#4444
200	-32000	—	historical state ... is not available; old data not available due to pruning...	No	No	—	Query blocks within the state window, or use Data API for historical queries.	JSON-RPC Docs	#-32000
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.	JSON-RPC Docs	#-32002
200	-32003	—	<node message>	No	No	—	Split batch into smaller requests to reduce response payload size.	JSON-RPC Docs	#-32003
200	-32600	—	<node message>	No	No	—	Inspect individual requests in the batch for non-compliant parameters; split and retry.	JSON-RPC Docs	#-32600
200	*	—	<node message>	Yes	No	—	Node performed computation and was billed. Inspect revert reason/data or call parameters; do not blindly retry.	JSON-RPC Docs	#*
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.	JSON-RPC Docs	#408

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	Related Doc	Anchor
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.	Data API Docs	#bad_request
409	not_indexed_yet	—	Requested block number is above current indexed head (carries indexed_through watermark)	No	Yes	Wait a few seconds until indexed_through reaches the block	Wait for the service to catch up to this block height and retry.	Data API Docs	#not_indexed_yet
409	finality_exceeded	—	Block is indexed but above finalized_block (not yet reorg-safe)	No	Yes	Wait for chain finality to advance	Wait for block finalization, or restrict query to blocks at or below meta.finalized_block.	Data API Docs	#finality_exceeded
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.	Data API Docs	#window_too_large
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.	Data API Docs	#too_many_pools
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.	Data API Docs	#span_exceeded
422	no_coverage	—	Capability not supported on this chain, or requested block is before the coverage window	No	No	—	Verify chain features and coverage.from_block via GET /v1/data/{chain}/status before querying.	Data API Docs	#no_coverage
503	unavailable	—	Data service temporarily unavailable, query slots busy, or shutting down	No	Yes	Wait a few seconds and retry with exponential backoff	Retry after a brief delay with exponential backoff.	Data API Docs	#unavailable

Console & Account API Errors

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

HTTP	Code	Reason	Meaning	Billed	Retryable	Wait Time (Retry-After)	Agent Action	Related Doc	Anchor
400	invalid_request	`invalid_username`	Username format is invalid (must be alphanumeric or underscores)	No	No	—	Provide a valid username adhering to username character and length requirements.	—	#invalid_username
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.	—	#expired
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.	—	#chain_mismatch
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.	—	#domain_mismatch
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.	—	#signature
409	key_limit_reached	`active_keys`	Active (non-revoked) API keys reached maximum account limit	No	No	—	Revoke an existing unused key before creating a new key.	—	#active_keys
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.	—	#nothing_to_reset
429	rate_limited	`daily_creations`	Account 24-hour key creation limit reached	No	Yes	Honor Retry-After header (seconds)	Rotate existing keys instead of creating new ones, or wait for 24-hour window to reset.	—	#daily_creations
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.	—	#per_ip
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.	—	#global
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/oauth/{provider}/start.	—	#oauth_invalid
400	login_code_invalid	—	Login code unknown, expired, already consumed, or PKCE verifier mismatch	No	No	—	Restart login to obtain a fresh login code.	—	#login_code_invalid
401	unauthenticated	—	Missing session, or session token is invalid, expired, or revoked	No	No	—	Sign in again to acquire a new Bearer session token.	—	#unauthenticated
403	user_disabled	—	Account has been suspended by administration	No	No	—	Contact contact@blockvectra.com for account support.	—	#user_disabled
404	provider_disabled	—	OAuth provider is recognized but currently disabled	No	No	—	Use SIWE or another supported authentication provider.	—	#provider_disabled
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.	—	#identity_in_use
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.	—	#identity_limit_reached
409	last_identity	—	Cannot unbind the sole remaining identity from the account	No	No	—	Bind another identity first before removing this one.	—	#last_identity
409	key_not_active	—	Attempted to rotate an API key that is disabled or revoked	No	No	—	Create a new key or rotate an active key.	—	#key_not_active
409	no_reset_available	—	No quota reset opportunities remain on this account	No	No	—	Contact contact@blockvectra.com to top up, or wait for next promotion cycle.	—	#no_reset_available
413	payload_too_large	—	Request body exceeds the 64 KiB size limit	No	No	—	Reduce request body size below 64 KiB.	—	#payload_too_large
429	rate_limited	—	Request rate limit exceeded on control plane API	No	Yes	Honor Retry-After header (seconds)	Sleep for duration in Retry-After before retrying.	—	#rate_limited
429	signup_rate_limited	—	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.	—	#signup_rate_limited
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.	—	#signup_paused
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.	—	#usage_unavailable
500	internal	—	Unexpected server error	No	Yes	Retry after a brief delay	Retry request with exponential backoff.	—	#internal