# Error Reference

> Original page: https://docs.blockvectra.com/en/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](https://docs.blockvectra.com/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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#parse_error](https://docs.blockvectra.com/en/errors/#parse_error) |
| 200 | -32600 | `invalid_request` | `invalid request` | No | No | — | Inspect request structure; verify jsonrpc: '2.0', id, and method fields before resending. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#invalid_request](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#batch_too_large](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#method_not_allowed](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#unknown_chain](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#logs_range_too_large](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#invalid_params](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#node_syncing](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#state_window](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#not_found](https://docs.blockvectra.com/en/errors/#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). | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#response_too_large](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#overloaded](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#key_rate_limit](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#free_plan_call_limit](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#concurrency_limit](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#request_exceeds_burst](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#free_plan_batch_too_large](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#upstream_unavailable](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#internal_error](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#balance_exhausted](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#free_grant_exhausted](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#missing_api_key](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#billing_unavailable](https://docs.blockvectra.com/en/errors/#billing_unavailable) |
| 200 | 4444 | — | `pruned history unavailable` | No | No | — | Block is outside the node's pruned history window; query historical blocks via Data API. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#4444](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#-32000](https://docs.blockvectra.com/en/errors/#-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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#-32002](https://docs.blockvectra.com/en/errors/#-32002) |
| 200 | -32003 | — | `<node message>` | No | No | — | Split batch into smaller requests to reduce response payload size. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#-32003](https://docs.blockvectra.com/en/errors/#-32003) |
| 200 | -32600 | — | `<node message>` | No | No | — | Inspect individual requests in the batch for non-compliant parameters; split and retry. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#-32600](https://docs.blockvectra.com/en/errors/#-32600) |
| 200 | * | — | `<node message>` | Yes | No | — | Node performed computation and was billed. Inspect revert reason/data or call parameters; do not blindly retry. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#*](https://docs.blockvectra.com/en/errors/#*) |
| 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. | [Doc](https://docs.blockvectra.com/en/api/json-rpc/) | [#408](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#bad_request](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#not_indexed_yet](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#finality_exceeded](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#window_too_large](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#too_many_pools](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#span_exceeded](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#no_coverage](https://docs.blockvectra.com/en/errors/#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. | [Doc](https://docs.blockvectra.com/en/api/data/) | [#unavailable](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#unauthenticated) |
| 403 | user_disabled | — | `Account has been suspended by administration` | No | No | — | Contact contact@blockvectra.com for account support. | — | [#user_disabled](https://docs.blockvectra.com/en/errors/#user_disabled) |
| 404 | provider_disabled | — | `OAuth provider is recognized but currently disabled` | No | No | — | Use SIWE or another supported authentication provider. | — | [#provider_disabled](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#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](https://docs.blockvectra.com/en/errors/#usage_unavailable) |
| 500 | internal | — | `Unexpected server error` | No | Yes | Retry after a brief delay | Retry request with exponential backoff. | — | [#internal](https://docs.blockvectra.com/en/errors/#internal) |