Batch requests

Incoming batch (client to eRPC)

A client can POST a JSON array of JSON-RPC objects to any eRPC endpoint. eRPC explodes it into individual requests, routes each one through the normal pipeline (selection policy, failsafe, cache, rate limits), then reassembles the responses in the original order before replying.

The response is always a JSON array with the same length as the request. HTTP status is always 200 OK even when individual items errored — inspect each item's error field.

Each item must carry a unique id field so eRPC can correlate responses. Items without id (notifications) are accepted but produce no response entry.

For multi-chain batches, add networkId: "evm:<chainId>" to each item and POST to the project root URL (/<projectId>). Single-chain batches go to the chain URL (/<projectId>/evm/<chainId>).

Outgoing batch (eRPC to upstream)

Controlled per-upstream via jsonRpc:

When supportsBatch: true, eRPC collects requests destined for the same upstream within the batchMaxWait window and sends them as a single HTTP request carrying a JSON array. If the batch hits batchMaxSize before the window expires it flushes immediately.

Outgoing batching is transparent to clients — it applies even to clients that send individual requests.

Interaction with the multiplexer (deduplication)

eRPC's multiplexer deduplicates in-flight requests by (network, method, params) before batching. If two clients send the same call concurrently, only one upstream request is made and both clients receive the same response. Deduplication happens before the outgoing batch is assembled, so it reduces batch size and upstream cost.

Interaction with cache

Cache lookups happen per-request before batching. A request that hits the cache is never forwarded upstream, whether the client sent it alone or inside a batch. A partial batch where some items are cached and some are not will only forward the cache-miss items to the upstream.

Per-request directives inside a batch

HTTP request headers (e.g. X-ERPC-Skip-Cache-Read, X-ERPC-Retry-Count) apply to the whole HTTP call. When a client sends a batch, the same headers apply to every item in that batch. There is no per-item header mechanism in JSON-RPC.

Response shape and ordering

eRPC preserves the original ordering of a batch response. If the upstream returns items in a different order (by id), eRPC reorders them to match the client's request array position before replying.

Common pitfalls

• batchMaxWait latency tradeoff — a non-zero wait adds guaranteed latency for every request. It is only worth setting when your upstream charges per HTTP request (not per method call) and you send many concurrent calls. For providers that charge per method call it saves nothing.
• Mixed-method batches — eRPC may route different items to different upstreams (e.g. based on method filters or circuit-breaker state). A batch to a client is assembled from responses that may have come from multiple upstreams.
• Error semantics — a batch item that fails returns {"id": ..., "error": {...}} in the array. The HTTP response is still 200. Clients must inspect each item individually.
• gzip interaction — if the upstream returns a gzip-compressed batch response, eRPC decompresses before exploding into individual items. The client-facing response is always uncompressed unless the client explicitly requested Accept-Encoding: gzip and eRPC is configured to forward it.
• Rate limits apply per request, not per batch — a 100-item batch consumes 100 units of the upstream's rate-limit budget.
• batchMaxSize is a flush trigger, not a hard cap — if batchMaxWait expires first, the batch may be smaller. Upstreams that enforce a strict cap may reject oversized batches with a top-level error; set batchMaxSize to match the provider's documented limit.