What is not billed: error codes and billing rules

BlockVectra meters requests in Compute Units (CU). JSON-RPC and Data API calls are billed only after a response is obtained. This guide summarizes the billing determination rules across HTTP status codes, JSON-RPC calls, and the Data API, along with recommended actions for developers.

HTTP status codes and billing rules

The billing determination and handling rules for HTTP-level responses are as follows:

The method rows below apply to ordinary HTTP requests to /v1/{chain} and /v1/{chain}/{api_key}, not named routes such as /v1/chains. A valid WebSocket upgrade follows the WebSocket capability and authentication checks instead of the plain GET/HEAD rules.

Note: When accessed through Cloudflare, Cloudflare may return 52x or 1015 error pages; these are not generated by the service.

Charge and balance response headers: When sending x-bv-meter: 1 on HTTP requests (applicable to both JSON-RPC and Data API), a response that billed at least one call returns x-bv-cu-charged (the Compute Units billed for this request, or the sum across billed calls of a batch) and x-bv-balance-units (the account's remaining balance units right after this charge, negative when overdrawn; omitted if the balance is unknown). Requests without x-bv-meter: 1, responses where nothing was billed, and 402, 403, 429, or 503 error responses omit both headers. These response headers are accessible to browser scripts via CORS, while WebSocket does not use them. The balance subtracts total unsettled usage rounded up once to whole units; hourly settlement rounds down, so the reported balance may rise by up to one unit after settlement.

JSON-RPC error codes and billing rules

The same error code can originate from the platform or the node, and billing differs:

• Errors generated by the platform itself: never billed;
• Errors returned by the node: passed through as-is and billed at the method weight, with only the node error codes listed below as exceptions.

Rule details

• Node errors not billed: The node's -32002 (batch timeout), -32003 (batch response too large), and -32600 (batch rejected as a whole) indicate that the node abandoned the call early; these and any notifications in the same batch are not billed. Node -32601 (exposed method not implemented) and -32603 (node internal failure) are not billed over HTTP or WebSocket and do not affect other calls or notifications in the batch. In addition, 4444 (pruned block) and -32000 (historical state outside the node's state history window, defined by state_window_blocks in GET /v1/chains) are not billed and do not affect other calls in the batch.
• Node errors billed: Other errors returned by the node are billed at the method weight when they report the chain's outcome, such as execution reverted (-32000 or 3 with data), the node's own -32602 invalid argument.
• Balance admission and sync: -32020 indicates insufficient account balance and requires a top-up; when the balance is known, error.data.balance_units and error.data.balance_cu carry what is left (it can be negative). A newly created key may return -32021 (503) for a few seconds; wait Retry-After and retry.
• Upstream failures: A -32603 generated by the platform due to upstream communication failure or malformed response (upstream unavailable, no response from upstream, malformed upstream response) carries data.reason: upstream_unavailable.
• Notification billing: Notifications (204) are billed at their method weights.

JSON-RPC error codes table

Data API billing rules

The Data API wraps read-only chain data into REST endpoints. Its billing and error handling follow these rules:

Rule details

• Only 2xx successful responses are billed.
• Unavailable operations outside coverage (such as unsupported chains or blocks outside trace coverage) return HTTP 422 no_coverage, which is not billed but counts toward rate limits.
• HTTP 401, 402, 404, and 429 responses are not billed. For response headers (x-bv-meter: 1), see HTTP status codes and billing rules.

Data API status codes table

Query balance (GET /v1/account)

An API key holder can check balance and key quota details directly without incurring any billing or deducting Compute Units (CU):

curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account

• Free and unbilled: GET /v1/account is free. It is never billed, does not deduct CU, and returns HTTP 200 with the current balance even when it is zero or negative (it never returns 402).
• Authentication: Key authentication uses the x-api-key header exclusively (path keys and Bearer tokens are not accepted). Missing header returns 401 missing_api_key; invalid or revoked keys return 401 invalid_api_key. (Expired keys return 403 key_expired; transient service unavailabilities return 503 auth_unavailable or billing_unavailable with Retry-After.)
• Rate limiting: Has an independent limit of 5 requests per second per key ID, independent of CU metering and billing (see “10. Limits at a glance” in the full OpenAPI reference). Exceeding the limit returns HTTP 429 rate_limited with a Retry-After header.

Response fields:

• key_id: The API key's identifier string.
• plan: Account plan type (free when the account has a free-plan call-rate allowance; paid otherwise).
• balance_units: Remaining account balance in units (may be zero or negative).
• balance_cu: Remaining balance converted to Compute Units (CU).
• balance_as_of_age_ms: Milliseconds elapsed since the balance was read from its data source.
• key: Key-specific limits and quota details:
  • cu_per_sec: Token-bucket refill rate in CU per second.
  • burst_cu: Token-bucket burst capacity in CU.
  • cu_cap: Lifetime CU cap for this key, or null if uncapped.
  • cu_cap_remaining: CU remaining under cu_cap, or null if uncapped (can be zero or negative).
  • expires_at: RFC 3339 expiration timestamp, or null if the key never expires.

Example response:

{
  "key_id": "<key_id>",
  "plan": "<plan>",
  "balance_units": <integer>,
  "balance_cu": <integer>,
  "balance_as_of_age_ms": <integer>,
  "key": {
    "cu_per_sec": <integer>,
    "burst_cu": <integer>,
    "cu_cap": <integer_or_null>,
    "cu_cap_remaining": <integer_or_null>,
    "expires_at": "<expires_at_or_null>"
  }
}

Pricing and upgrades

The specific cost for all billed calls is determined by published CU weights:

• To inspect weights for all methods and operations, see the method weight table and the JSON-RPC CU Metering Rules.
• For plan pricing and settlement details, see the Pricing page.
• Upgrading to a paid plan: making a paid top-up removes the Free Plan's per-second call limit; each key remains subject to CU rate and burst limits.

On-Chain Top-up Process

When your account balance is insufficient or you need higher throughput, top up on-chain in the console following these steps:

1. Log in to the Console: Sign in to the BlockVectra Console.
2. Go to the Billing Page: Navigate to the Billing page.
3. Get Your Dedicated Address: In the on-chain top-up card, copy your account's dedicated top-up address or scan the QR code.
4. Transfer Funds: Transfer only using the supported networks and USDC / USDT / USDG listed on the page. Supported networks and minimum top-up amounts are shown in the console.
5. Automatic Crediting: Once detected on-chain, transactions show as "Processing"; once credited, credits are automatically added to your balance.

Important Notes:

• Only use the networks and tokens explicitly listed in the console. Transfers on unsupported chains or with wrong tokens cannot be credited automatically.
• Ensure each transfer meets the minimum top-up amount indicated in the console.
• Once your first paid top-up is credited, your account is upgraded to a paid account, removing the Free Plan's per-second call limit.

Agent or server programs can directly call top-up endpoints using an API key; see the Agent programmatic top-up guide.

Webhook push billing

Push has separate weights for delivered data events, successful history queries and billable address-days. Management calls other than event history, failed delivery attempts, automatic retries and control events are free. Each delivered event is charged once; customer replay and canonical events redelivered after a reorg are new billed deliveries. Address charges use each subscription’s maximum address count while online during the UTC day; the account free-address allowance is shared across subscriptions, with older subscriptions using it first. An address in two subscriptions is counted twice; adding chains changes event fees, not address fees.

See the Blockchain Webhook API guide for setup, signature verification and delivery recovery. The stablecoin payment guide covers receipt validation and polling backfill; WebSocket subscriptions use their own connection and notification metering. Request errors are listed in the error reference. The weights below come from GET /v1/plans.

Next steps

• Browse the datasets directory to see every dataset BlockVectra indexes.
• See the free plan and pricing to check what your account includes.
• Log in to the console to create an API key.