Limits and errors

A request that Willow cannot serve completely is refused with an error, never answered with a partial or empty result. An empty result therefore means that no matching logs exist in the requested blocks. The error states the reason for the refusal, and in most cases a router can send the request to another provider.

Rate limits

Each plan sets a rate limit in requests per second. Each item in a batch counts as one request.

Plan	Requests per second
Free	25
Pay as you go	100
Builder	100
Scale	300

The limit applies to the account: all of an account’s keys share it. A key can have a lower limit of its own. A request over the limit is refused with HTTP 429 and code -32005. Back off and retry.

An account may also have two eth_getLogs calls reading blocks concurrently (one on Free). See Range limits.

Usage limits (included units, the balance, and the spend cap) are described in Units and pricing. Proof limits are described in Log proof methods.

Errors

HTTP	Code	Meaning	Remedy
200	-32000	Not found: the block is beyond the newest block, the chain is catching up, the tag is finalized or safe where it is not served or cannot be verified, the block hash or transaction is unknown, the blocks are not held or are being fetched, the server is busy reading blocks for other requests, the chain is not served, or a proof is not yet ready. Every refusal of a standard method contains “not found”. error.data with history indicates a fetch in progress, and with status that a proof was queued.	Fall back to another provider. For a fetch or a queued proof, repeat the request after retryAfterSeconds.
200	-32002	Too large: more than 10,000 logs, a request’s eth_getLogs items exceeding their shared 2 seconds, a history fetch over 100,000 blocks, a proof exceeding its size limits or 20-second deadline, or a proof request exceeding the key’s job limits. Size messages contain “range too large” or “returned more than”, and most specify a range that fits.	Narrow the block range and retry, or fall back.
200	-32602	Invalid params: fromBlock after toBlock, malformed hex, blockHash combined with a range, an invalid proof id, or an index beyond the block’s last transaction. Also a proof request that requires acceptance (error.data.status is "quote").	Correct the request, or resend it with "acceptQuote": true.
200	-32601	Method not supported. Also returned for log proof methods on the Free plan, for state methods on a plan that does not include them, and for eth_call on a chain other than Ethereum or with state or block overrides.	Send this method to another provider.
200	3	eth_call reverted. error.data holds the revert data.	Return the error to the client. The result is final, so do not fall back.
200	-32600	Invalid request: missing method, an empty batch, or a batch of more than 100.	Correct the request.
200	-32603	Internal error.	Fall back, and report the error to Willow if it persists.
200	-32700	Parse error: the body is not valid JSON.	Correct the body.
401	-32000	Invalid, missing, revoked, or suspended key.	Correct or replace the key. See API keys.
402		Payment required: the balance is exhausted, the spend cap is reached, or the balance cannot pay for a proof. The body is in the x402 format.	Add credit or choose a plan in the dashboard. See below.
403	-32000	The key is not enabled for this chain or this origin.	Use a key that is enabled, or change the key’s limits.
429	-32005	Rate limit exceeded for this account or key, or too many requests with invalid keys from one address.	Back off and retry.

State methods return further -32000 refusals, and -32000 without “not found” for a halted eth_call, which is a final result. See State methods.

-32005 is returned only with HTTP 429, for the rate limit and for repeated requests with invalid keys. A request that is too large is refused with -32002 and HTTP 200, so a router that pauses a provider after -32005 does not pause Willow because of a single oversized query.

Examples

-32000, not found:

{"error":{"code":-32000,"message":"not found in this store: block 26148864 is beyond the indexed range 26118506-26120035"},"id":5,"jsonrpc":"2.0"}

-32002, too large:

{"error":{"code":-32002,"message":"query returned more than 10000 results. Try with this block range [0x190bca0, 0x190bca6]."},"id":1,"jsonrpc":"2.0"}

-32602, invalid params:

{"error":{"code":-32602,"message":"invalid params: fromBlock 26119980 is after toBlock 26119977"},"id":9,"jsonrpc":"2.0"}

-32601, method not supported:

{"error":{"code":-32601,"message":"the method eth_newFilter does not exist/is not available"},"id":6,"jsonrpc":"2.0"}

-32700, parse error:

{"error":{"code":-32700,"message":"parse error: EOF while parsing a value at line 1 column 24"},"id":null,"jsonrpc":"2.0"}

HTTP 401:

{"error":{"code":-32000,"message":"invalid API key"},"id":null,"jsonrpc":"2.0"}
{"error":{"code":-32000,"message":"API key required: /rpc/{chain}/{key}, or the key in an Authorization: Bearer or X-API-Key header"},"id":null,"jsonrpc":"2.0"}

402 Payment Required

A request is refused with HTTP 402 when the key’s account cannot pay:

• The balance is exhausted. The account has no included units remaining, and no balance or overage to pay for more. Every request with the account’s keys is refused with 402 until the balance is topped up or the next period starts.
• The spend cap is reached. The account has reached its spend cap. A payment cannot lift the cap; it must be raised in the dashboard.
• A proof cannot be paid for. The blocks of a proof request cost more than the balance and proof credit can cover. The entire HTTP request is refused with 402, and no charge is made.
• The remaining balance is reserved. The remainder of the balance is held for history fetches in progress.

The body is a JSON-RPC envelope in the x402 version 1 format. As in x402, error is a plain string rather than a JSON-RPC error object, so a router handles the 402 by its HTTP status:

{
  "jsonrpc": "2.0",
  "id": 1,
  "x402Version": 1,
  "error": "payment required: this API key's balance is used up; top it up with an x402 payment for one of accepts (v1 in X-PAYMENT, v2 in PAYMENT-SIGNATURE) or in the dashboard",
  "accepts": []
}

accepts lists the x402 payments that Willow accepts for a top-up. Payment in USDC over x402 is not yet offered, so accepts is empty and a payment header is refused.

To continue, add credit on the Billing page, or choose a plan there. The key is usable again within seconds.

Unknown chains and methods

A request for a chain Willow does not serve is refused with -32000 (chain N not found: no blocks of it are served here). A request for an unsupported method is refused with -32601. Using Willow behind a router describes how to send these requests to another provider automatically.