RPC Timeout Error: Causes, Diagnosis, and Fixes

What Is an RPC Timeout Error?

An RPC timeout error is a client-side exception raised when a JSON-RPC request to a blockchain node does not complete within a specified time limit. The client sends a request (e.g., eth_getBlockByNumber) and waits for a response; if the node does not reply before the timeout expires, the client aborts the request and surfaces an error like TimeoutError, ETIMEDOUT, or request timed out.

Timeouts are not a blockchain-specific concept—they are a fundamental part of any distributed system. In the context of blockchain RPC, timeouts can occur at multiple layers: the network (TCP connect timeout), the HTTP request (read timeout), or the application logic (e.g., waiting for a transaction receipt). Understanding which layer is failing is the first step in troubleshooting.

This article focuses on Ethereum-compatible JSON-RPC, but the principles apply to other chains like Solana and Polkadot. For a broader overview of RPC endpoints, see our RPC endpoints guide.

• Client-side timeout: the client gives up waiting for a response.
• Server-side timeout: the node or provider terminates a slow request.
• Network timeout: packets are lost or delayed beyond acceptable thresholds.

Common Causes of RPC Timeouts

RPC timeouts are rarely caused by a single factor. They typically stem from a combination of network conditions, node performance, and client configuration. The most common causes include:

Network latency and packet loss – If your client is geographically distant from the RPC endpoint, or if the network path is congested, round-trip time (RTT) can exceed your timeout. This is especially common when using public endpoints that are far away.

Overloaded or under-provisioned nodes – A node that is syncing, processing many requests, or running on insufficient hardware may respond slowly. Public endpoints often rate-limit or queue requests, causing delays.

Large or expensive requests – Some RPC methods, like eth_getLogs with a wide block range, can take seconds to execute. If your client timeout is set to 2 seconds, such requests will inevitably time out.

Misconfigured client timeouts – Many libraries default to short timeouts (e.g., 10 seconds in web3.js, 30 seconds in ethers). If your application does not explicitly set a timeout, you may be using a value that is too low for your use case.

Provider-side issues – RPC providers may have their own timeout policies. For example, a provider might terminate requests that take longer than 30 seconds. If your request is slow, you may see a timeout even if your client is configured correctly.

• Check your client's default timeout and adjust it based on your request patterns.
• Use a provider with a service-level agreement (SLA) that guarantees response times.

Diagnosing RPC Timeouts with curl

The quickest way to diagnose an RPC timeout is to use curl to send a request and measure the timing. The -w flag outputs timing details, and --max-time sets a timeout for the entire request. Here's a command that sends a simple eth_blockNumber request to a public Ethereum endpoint:

curl -s -o /dev/null -w "connect: %{time_connect}s\nttfb: %{time_starttransfer}s\ntotal: %{time_total}s\n" --max-time 10 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

The output shows the time to establish a TCP connection (time_connect), the time to receive the first byte (time_starttransfer), and the total time. If time_connect is high, you have a network issue. If time_connect is low but time_starttransfer is high, the node is slow to respond.

If the command times out (exit code 28), you know the endpoint is not responding within your limit. Try the same request against a different endpoint, such as a dedicated RPC endpoint, to see if the issue is provider-specific.

curl -s -o /dev/null -w "connect: %{time_connect}s\nttfb: %{time_starttransfer}s\ntotal: %{time_total}s\n" --max-time 10 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Testing with a Heavy Request

A simple eth_blockNumber request is fast, but many timeouts occur with heavier methods. To reproduce a timeout, send a request that requires more computation, such as eth_getLogs over a large block range. Use the same curl timing flags to see how long it takes:

curl -s -o /dev/null -w "total: %{time_total}s\n" --max-time 30 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x1000000","toBlock":"0x1000100","address":"0x..."}],"id":1}'

If this times out, you have a request that is too heavy for the endpoint. In production, you should avoid such requests or use batching and pagination. See our guide on JSON-RPC batching best practices for strategies to reduce payload size.

Also note that some providers impose their own limits on eth_getLogs (e.g., maximum block range). If you exceed those limits, you may get an error or a timeout.

curl -s -o /dev/null -w "total: %{time_total}s\n" --max-time 30 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x1000000","toBlock":"0x1000100","address":"0x..."}],"id":1}'

Client-Side Timeout Configuration

Most Web3 libraries allow you to set a timeout. In ethers.js, you can pass a timeout option to the provider or use request with a timeout. In web3.js, you can set timeout in the provider options. Here's an example with ethers.js:

const { ethers } = require("ethers");
const provider = new ethers.JsonRpcProvider("https://eth.api.onfinality.io/public", undefined, { timeout: 15000 });

Setting a timeout that is too low will cause frequent timeouts on slow networks. A common practice is to set a timeout of 15-30 seconds for standard requests, and up to 60 seconds for heavy operations like eth_getLogs or eth_call that involve complex contract logic.

If you are using a library that does not expose a timeout, you can wrap your request in a Promise.race with a timer. This gives you fine-grained control over the timeout for each call.

Remember that timeouts are not a substitute for proper error handling. Always catch timeout errors and implement retry logic with exponential backoff. For more on this, see our monitoring RPC endpoints guide.

const { ethers } = require("ethers");
const provider = new ethers.JsonRpcProvider("https://eth.api.onfinality.io/public", undefined, { timeout: 15000 });

Provider-Side Timeouts and Limits

RPC providers often have their own timeout policies. For example, a provider may terminate any request that takes longer than 30 seconds. This is to protect their infrastructure from resource exhaustion. If your request is slow, you may see a timeout even if your client is configured correctly.

Providers also impose rate limits and concurrency limits. If you exceed these, you may receive HTTP 429 or 503 errors, which can be mistaken for timeouts. Check the response headers for x-ratelimit-* or similar.

When choosing an RPC provider, consider their SLA and performance guarantees. OnFinality, for instance, offers dedicated endpoints with no rate limits and 24/7 monitoring. You can compare providers in our best RPC provider guide.

If you are running your own node, ensure it is well-provisioned (CPU, RAM, disk) and not lagging behind the network. A node that is still syncing will respond slowly or not at all.

• Check provider documentation for timeout and rate limit policies.
• Use a provider that offers dedicated endpoints for production workloads.

Network-Level Timeouts and Firewalls

Sometimes the issue is not the node but the network path. Firewalls, proxies, and load balancers can introduce latency or drop packets. To diagnose, use ping and traceroute to measure latency and packet loss to the RPC endpoint's hostname.

ping -c 10 eth.api.onfinality.io
traceroute eth.api.onfinality.io

If you see high latency or packet loss, consider using a different endpoint that is geographically closer. Many providers offer endpoints in multiple regions. OnFinality, for example, has a global network of nodes; you can select the closest one via our network page.

Also check your local firewall or corporate proxy settings. Some networks block or throttle traffic to unknown ports or hosts. If you are behind a proxy, ensure that your RPC client is configured to use it.

ping -c 10 eth.api.onfinality.io
traceroute eth.api.onfinality.io

Common Error Messages and Their Meanings

Different clients and providers return different error messages for timeouts. Here are some common ones and what they mean:

| Error Message | Likely Cause |

|---------------|--------------|

| ETIMEDOUT | Network connection timed out (TCP connect or read). |

| TimeoutError | Client-side timeout exceeded. |

| request timed out | Generic timeout from HTTP client. |

| ECONNRESET | Connection reset by server (often due to rate limiting or server overload). |

| 429 Too Many Requests | Rate limit exceeded, not a timeout but often confused. |

| 503 Service Unavailable | Server overloaded or under maintenance. |

If you see ECONNRESET or 429, you are likely hitting rate limits. In that case, reduce your request rate or use a provider with higher limits. For timeouts, focus on the causes discussed above.

• Always log the full error object, including stack trace and response headers.
• Use a correlation ID to trace requests across your system.

Preventing RPC Timeouts in Production

To minimize RPC timeouts in production, adopt the following practices:

Use a reliable RPC provider – Choose a provider with a proven track record and SLA. Avoid free public endpoints for critical applications.

Set appropriate timeouts – Configure timeouts based on the expected response time of each method. Use longer timeouts for heavy operations.

Implement retry logic – Retry failed requests with exponential backoff and jitter. This handles transient network issues.

Batch requests – Combine multiple RPC calls into a single JSON-RPC batch to reduce the number of round trips. See our batching guide.

Cache responses – Cache frequently requested data (e.g., token prices, block numbers) to reduce the load on RPC endpoints.

Monitor performance – Use tools to track RPC latency and error rates. Our monitoring guide provides practical steps.

Use a load balancer – If you have multiple endpoints, distribute requests across them to avoid overloading a single node.

• Consider using a dedicated API service that handles scaling and failover for you.

Tradeoffs and Limitations

Increasing timeouts can mask underlying issues. If your requests consistently take longer than expected, you should investigate the root cause rather than simply raising the timeout. Long timeouts also tie up client resources and can lead to poor user experience.

Retry logic can cause duplicate transactions if you retry a request that was actually processed but the response was lost. Use idempotency keys or check transaction hashes before retrying.

Batching reduces round trips but can increase the payload size, which may hit provider limits. Always check the maximum batch size supported by your provider.

Finally, no solution is perfect. Even with the best practices, occasional timeouts are inevitable due to network unpredictability. Design your application to handle them gracefully.

Next Steps

Now that you understand RPC timeouts, you can take concrete steps to diagnose and fix them. Start by running the curl commands in this article against your endpoints to measure baseline latency. Then, adjust your client timeouts and implement retry logic.

For further reading, explore our RPC Assistant for more troubleshooting guides, or learn how to reduce RPC latency to improve performance.

If you are evaluating RPC providers, compare pricing and features to find a solution that meets your needs.