Throughput

Understand how throughput works on Alchemy and how to handle 429 errors.

What is throughput?

"Throughput" refers to the volume of requests you can successfully send to Alchemy within a given time frame — and is primarily governed by the throughput limit set for your account.

How throughput on Alchemy works

Throughput is defined in terms of CU/s (Compute Units Per Second). Some key aspects:

• Throughput is now configured at the account level (no longer per app), meaning the combined usage of all your Alchemy apps counts toward your overall throughput limit.
• Limits are evaluated over a 10-second rolling window using a token bucket algorithm with strict refill rates. For example, a Free tier customer with a 300 CU/s limit can consume up to 3,000 CUs over any 10-second period. This design helps accommodate short-term traffic spikes without exceeding the overall limit.
• Throughput limits scale based on your plan tier.

Error response

When you exceed your capacity, you receive an error response. This response differs depending on whether you're connecting to Alchemy using HTTP or WebSockets.

If you would like to test receiving a 429 response, send a POST request to https://httpstat.us/429.

HTTP

You will receive an HTTP 429 (Too Many Requests) response status code.

WebSockets

You receive a JSON-RPC error response with error code 429. For example, the response might be:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 429,
    "message": "Your app has exceeded its compute units per second capacity. If you have retries enabled, you can safely ignore this message. If not, check out /docs/reference/throughput"
  }
}

Retries

There are several options for implementing retries. For a deep dive into each option, check out How to Implement Retries.

To handle 429 errors, retry the request. This ensures a great experience with any API even if you aren't hitting rate limits. Once you've implemented retries, test out the behavior to make sure they work as expected.

Option 1: Retry-After

If you are using HTTP and not WebSockets you may receive a Retry-After header in the HTTP response. This indicates how long you should wait before making a follow-up request. We still recommend using exponential backoff since Retry-After only accepts an integer number of seconds.

Option 2: Simple retries

If exponential backoff poses a challenge to you, a simple retry solution is to wait a random interval between 1000 and 1250 milliseconds after receiving a 429 response, and sending the request again, up to some maximum number of attempts you are willing to wait.

Option 3: Exponential backoff

Exponential backoff is a standard error-handling strategy for network applications. It's similar to retries, but instead of waiting random intervals, an exponential backoff algorithm retries requests exponentially, increasing the waiting time between retries up to a maximum backoff time.

Example algorithm:

1. Make a request.
2. If the request fails, wait 1 + random_number_milliseconds seconds and retry the request.
3. If the request fails, wait 2 + random_number_milliseconds seconds and retry the request.
4. If the request fails, wait 4 + random_number_milliseconds seconds and retry the request.
5. And so on, up to a maximum_backoff time.
6. Continue waiting and retrying up to some maximum number of retries, but do not increase the wait period between retries.

where:

• The wait time is min(((2^n)+random_number_milliseconds), maximum_backoff), with n incremented by 1 for each iteration (request).
• random_number_milliseconds is a random number of milliseconds less than or equal to 1000. This helps to avoid cases in which many clients are synchronized by some situation and all retry at once, sending requests in synchronized waves. The value of random_number_milliseconds is recalculated after each retry request.
• maximum_backoff is typically 32 or 64 seconds. The appropriate value depends on the use case.

The client can continue retrying after it has reached the maximum_backoff time. Retries after this point do not need to continue increasing backoff time. For example, suppose a client uses a maximum_backoff time of 64 seconds. After reaching this value, the client can retry every 64 seconds. At some point, clients should be prevented from retrying indefinitely.

Test throughput and retries

To test out your implementation of retries, we created a test app on each network with a low throughput of 50 Compute Units/Second. The same key can be used across all the blockchains we support. Feel free to make requests to this test app on any of the networks using the following API keys:

Ethereum mainnet, Polygon mainnet (and other mainnets)

HTTP

https://eth-mainnet.g.alchemy.com/v2/J038e3gaccJC6Ue0BrvmpjzxsdfGly9n

WebSocket

wss://eth-mainnet.g.alchemy.com/v2/J038e3gaccJC6Ue0BrvmpjzxsdfGly9n

Ethereum Sepolia, Polygon Amoy (and other testnets)

HTTP

https://eth-sepolia.g.alchemy.com/v2/AxnmGEYn7VDkC4KqfNSFbSW9pHFR7PDO

WebSocket

wss://eth-sepolia.g.alchemy.com/v2/AxnmGEYn7VDkC4KqfNSFbSW9pHFR7PDO

Any other questions?

Reach out to support@alchemy.com with any questions.