A JSON-RPC batch puts several calls in one request. The reply array is not a positional mirror of the request array. Treating payload[i] as the answer to requests[i] can bind every result to the wrong call while the transport still reports success. Here is a three-response mismatch:

const requests = [
  { jsonrpc: "2.0", id: 7, method: "eth_blockNumber", params: [] },
  { jsonrpc: "2.0", id: 8, method: "eth_getBalance", params: ["0x0000000000000000000000000000000000000000", "latest"] },
  { jsonrpc: "2.0", id: 9, method: "eth_chainId", params: [] },
];

const payload = [
  { jsonrpc: "2.0", id: 9, result: "0x1" },
  { jsonrpc: "2.0", id: 7, error: { code: -32000, message: "busy" } },
  { jsonrpc: "2.0", id: 8, result: "0x0" },
];

requests.forEach((request, index) => {
  const response = payload[index];
  console.log(request.id, response.id);
});
// 7 9
// 8 7
// 9 8

Every request is paired with another request's id. Request 7 is now "answered" by id 9's chain id, request 8 by id 7's error, and request 9 by id 8's balance. If the caller only checks that three responses arrived, the batch looks complete. A downstream parser may then apply an eth_chainId result where an eth_blockNumber result was expected. These are offline synthetic fixtures, not real calls, results, or balances.

The specification permits this: response objects "MAY be returned in any order within the Array." The stable join key is the id carried by both the request and its response. A response's position carries no contract.

HTTP 200 is not batch success

A batch can return HTTP 200 while containing an item-level error. In the example above, the middle entry is an error for id 7; id 9 still has a result. A status-code check sees only transport success. Code that scans for the first non-error entry, or that assumes every array entry is a result, can silently skip the failed call.

The same rule applies to completeness. A missing response, a duplicate response id, or a response id that was never sent means the client cannot confirm a complete batch. A malformed whole batch may be returned as one error object instead of an array. That object cannot be paired with any request, so it should be reported as uncorrelated rather than attached to the first request or copied to all of them.

Each response must carry exactly one of result or error, and an error must be a non-null object with an integer code and a string message. A result is allowed to be false, 0, or null; checking truthiness is not a valid presence test.

A strict correlator

The complete implementation follows. It is dependency-free and can be copied as one module.

const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);

const isPositiveSafeInt = (value) => Number.isSafeInteger(value) && value > 0;

function fail(message) {
  throw new Error(`correlateBatch: ${message}`);
}

function assertErrorShape(error, id) {
  if (error === null || typeof error !== "object" || Array.isArray(error)) {
    fail(`request ${id} returned a non-object error`);
  }
  if (!Number.isInteger(error.code) || typeof error.message !== "string") {
    fail(`request ${id} returned a malformed error`);
  }
}

/**
 * Correlate a JSON-RPC 2.0 batch response array with its requests by id.
 * This checks envelope, id, and error shape only, not result semantics.
 */
export function correlateBatch(requests, payload) {
  if (!Array.isArray(requests) || requests.length === 0) {
    fail("requests must be a non-empty array");
  }
  const expected = new Set();
  for (const request of requests) {
    if (request === null || typeof request !== "object" || !hasOwn(request, "id")) {
      fail("every request must be an object with its own id");
    }
    if (!isPositiveSafeInt(request.id) || expected.has(request.id)) {
      fail("request ids must be unique positive safe integers");
    }
    expected.add(request.id);
  }
  if (!Array.isArray(payload) || payload.length === 0) {
    fail("uncorrelated: response payload must be a non-empty array");
  }
  const responses = new Map();
  for (const row of payload) {
    if (row === null || typeof row !== "object" || Array.isArray(row)) {
      fail("every response row must be a non-null object");
    }
    if (row.jsonrpc !== "2.0") {
      fail("every response row must declare jsonrpc 2.0");
    }
    if (!hasOwn(row, "id")) {
      fail("every response row must carry its own id");
    }
    if (!expected.has(row.id)) {
      fail(`unknown response id ${String(row.id)}`);
    }
    if (responses.has(row.id)) {
      fail(`duplicate response id ${row.id}`);
    }
    const hasResult = hasOwn(row, "result");
    const hasError = hasOwn(row, "error");
    if (hasResult === hasError) {
      fail(`request ${row.id} must carry exactly one of result or error`);
    }
    if (hasError) {
      assertErrorShape(row.error, row.id);
    }
    responses.set(row.id, row);
  }
  for (const id of expected) {
    if (!responses.has(id)) {
      fail(`missing response id ${id}`);
    }
  }
  return responses;
}

It first validates the expected ids. It then rejects non-object rows, a wrong jsonrpc version, a missing row id, an unknown id, a duplicate id, and a result/error pair that is not exactly one present. Finally, it checks that every expected id was seen. The returned Map keeps the original response object for each id, so a result or error is not rewritten.

Consume successes, fail on errors

The snippet is application pseudocode. validateForMethod and consume are application-provided; only the correlator above is a complete, copyable module.

import { correlateBatch } from "./batch-response.mjs";

const byId = correlateBatch(requests, payload);

const values = requests.map((request) => {
  const response = byId.get(request.id);
  if (Object.hasOwn(response, "error")) {
    throw new Error(`RPC ${response.error.code}: ${response.error.message}`);
  }
  return validateForMethod(request.method, response.result);
});

for (const value of values) {
  consume(value);
}

Callers should iterate over the requests they sent, look up each response by id, and handle the two branches explicitly. Error entries remain errors. This helper does not turn an RPC error into a successful value, retry it, or advance a checkpoint. The map step validates the whole batch before any consume call, so later errors block earlier consumptions. This is application ordering, not a database transaction or all-or-nothing guarantee; persistence and checkpoint advancement stay with the application. A job that needs retries should make that decision outside the correlator and should only advance a checkpoint after every required call has a validated success.

Do not skip the method-specific step. A syntactically valid result can still be the wrong shape for eth_getLogs, eth_getBalance, or any other method. Envelope validation is not result validation.

Scope and limits

This example is deliberately stricter than the full protocol. It expects non-empty read-only requests whose ids are unique positive safe integers. It does not cover notifications, null ids, string ids, or fractional ids. Those are constraints chosen for this example, not claims that JSON-RPC forbids other id forms. The function checks envelope, id, and error shape only. It does not validate method result semantics, chain or finality, checkpoints, or the whole protocol.

Batch size and concurrency are different budgets. Batch size is how many calls go into one request; concurrency is how many requests are in flight. Lowering one does not automatically lower the other. Joining responses by id fixes correlation; it does not remove a provider's batch limit or concurrency limit.

If you are querying logs over a block range, the BlockVectra getLogs guide is a natural next step: Get logs over a block range.

By BlockVectra, with AI-assisted drafting. The code was run locally with Node's built-in test runner; independent review is not claimed.

Runnable MIT companion and 14 offline checks: code and tests. Download both .mjs files and run node --test batch-response.test.mjs.

A wallet can receive HTTP 200 and still display the wrong portfolio. Two particularly quiet mistakes are treating unknown token decimals as zero and feeding a paginated response object into a parser that expects an array.

Unknown decimals are different from zero

In BlockVectra’s documented address-balance schema, balance is a decimal integer string. decimals is an integer from 0 through 255, or null; symbol can also be null.

Zero decimals is a known scale. Null means the scale is unknown. JavaScript coercion erases that distinction:

import assert from 'node:assert/strict';

assert.equal(Number(null), 0);
assert.equal(Number('9007199254740993').toString(), '9007199254740992');

const row = { balance: '9007199254740993', decimals: null, symbol: null };
assert.equal(BigInt(row.balance), 9007199254740993n);
assert.equal(row.decimals, null);
assert.notEqual(row.decimals, 0);

This is a synthetic row excerpt, not a complete API response. The assertions reproduce coercion and integer precision loss locally; they make no network requests. Preserve the raw balance string. Use an exact integer/decimal representation for calculations, and leave the scaled amount unknown when decimals is null. Do not invent a symbol or infer a zero balance from missing metadata. BigInt helps with integer arithmetic; convert it back to a string before JSON serialization.

An envelope is not a token array

The documented response to GET /v1/data/{chain}/addresses/{address}/balances has data, meta, and an optional next_cursor. Only data is the token array. A bare-array parser that silently returns [] for any object can turn an integration error into a convincing empty wallet.

Handle HTTP and response-shape failures separately from a valid empty data array. Follow the opaque next_cursor unchanged until it is absent. Preserve failures on later pages too: a partial first page is not a complete portfolio. Keep null distinct from absence where the contract makes that distinction; the final page omits next_cursor.

Indexed head is not snapshot time

For balances, meta.as_of_block describes the current indexed head. It does not give the balance snapshot’s height or update time. Read meta.refreshed_at for the snapshot update time; null means stale or unknown update time. A coverage label is not a freshness guarantee.

Before choosing this endpoint for a chain, check that chain’s data_features and data_status in GET /v1/status. Unsupported coverage returns 422 no_coverage. This article does not establish current coverage for any particular chain.

Adapter cases worth retaining

Test an explicitly empty successful page, an HTTP/HTML error, an unexpected response shape, several cursor pages, a failed later page, a balance above the safe integer range, null decimals versus zero decimals, and null snapshot time. These are suggested integration cases, not completed end-to-end tests.

The wallet assets guide covers the endpoint and snapshot semantics. The public Data API schema defines UInt256String, AddressBalance, AddressBalanceListEnvelope, and Meta. The contract snapshot used here was saved on 2026-10-20; verify the current contract before implementing an adapter.

Here is the arithmetic: the inclusive range 42..42 contains one block, although 42 minus 42 is zero. For 10..110, the distance is 100 but the range contains 101 blocks.

The failure is in range planning

While investigating ERC-20 history queries in Bitcore, we reproduced a loop that skipped a single-block range and certain final one-block remainders. The proposed fix changes the loop condition from windowSize > 0n to windowSize >= 0n in that implementation. This is a client-side omission: the missing request never reaches a provider.

The proposed patch and seven provider-level regressions are public. This article describes the patch at commit c42c8a7a67899a3f955080faddd0b2de54bbcc4a; a contribution is not a claim that an upstream release includes it or that its maintainers endorse BlockVectra.

Do not copy that condition change into every loop. Its correctness depends on what the variable means. If a variable is a count of remaining blocks, zero means finished. If it is the distance between inclusive endpoints, zero still means one block.

A small, executable boundary check

This separate range planner makes the inclusive endpoints explicit. Save it as inclusive-ranges.mjs and run node inclusive-ranges.mjs. It needs no package install, account, API key or network connection. Inputs in this example are BigInts; 50 is an illustrative chunk size, not a provider limit.

import assert from "node:assert/strict";

function ranges(from, through, maxBlocks) {
  if (from < 0n || through < 0n || maxBlocks <= 0n) {
    throw new RangeError("Nonnegative bounds and positive size required");
  }
  const result = [];
  while (from <= through) {
    const candidate = from + maxBlocks - 1n;
    const end = candidate < through ? candidate : through;
    result.push([from, end]);
    from = end + 1n;
  }
  return result;
}

assert.deepEqual(ranges(42n, 42n, 50n), [[42n, 42n]]);
assert.deepEqual(ranges(10n, 110n, 50n), [
  [10n, 59n], [60n, 109n], [110n, 110n],
]);
assert.deepEqual(ranges(10n, 109n, 50n), [
  [10n, 59n], [60n, 109n],
]);
assert.throws(() => ranges(0n, 1n, 0n), RangeError);
console.log("Four offline range checks passed");

The cases deliberately include one block, a final one-block remainder, an exact boundary, and a zero-size rejection. Test the query parameters and returned records at the real provider boundary too: a separate planner passing checks does not prove a production caller uses it correctly. This planner returns no ranges when the start is already beyond the upper bound; do not send reversed bounds to an RPC method.

A correct range still needs a durable checkpoint

Once the range exists, fetching and committing are separate operations. Use a fixed upper-bound snapshot for one backfill pass, read a chunk, validate the response shape, then durably store its logs and checkpoint together. Advance the in-memory start only after that commit succeeds.

For example, after committing through block 109, the next start is 110. If the request for block 110 fails, or its database transaction fails, the durable checkpoint must remain at 109. A restart should retry 110. Conversely, a successful empty log array can be committed for a completed range; an empty result is not automatically an error.

A crash between writing logs and writing the checkpoint can otherwise create duplicate work or skipped work. Implement atomic persistence in your own database adapter and make retried writes idempotent. Scope the checkpoint to the chain, contract/filter and decoder or schema version.

Our original MIT-licensed backfill example includes an injected-client helper and nine previously run offline mock tests for chunk boundaries, failure/resume, malformed responses and consumer failure. It delegates atomic persistence to the caller; it is not a database adapter or a released production SDK.

Three checks that remain outside the loop

First, an array-shaped response is not proof of completeness. A provider can return a syntactically valid array that omits matching logs. Range arithmetic and shape checks do not establish that every canonical event was returned.

Second, a head snapshot is an upper bound, not a finality guarantee. Verify the target chain before use, retain the information your canonicality checks need, and implement an explicit finality and reorg policy.

Third, distinguish request size from shared capacity. A narrower range may help an oversized query. It does not by itself fix a saturated shared budget. Bound concurrent requests and retries with a real overall deadline; a single-block failure cannot be fixed by splitting the block range forever.

The useful acceptance test is concrete: can a one-block range be requested, can its final result be committed, and can a crash resume from the last durable checkpoint without inventing progress?

Prepared by BlockVectra's AI assistant from source inspection and offline checks. The code example above was run locally; no production RPC was called for this article. BlockVectra builds RPC and Agent tooling; its public MCP connection repository is separate from this injected-client example. Related documentation: RPC log-range limits. JSON-RPC method reference: eth_getLogs.