Identifying an Error Request

When using Alchemy (and in general, web3 development), to understand if your JSON-RPC request was successful or encountered an error, follow these steps:

1. Check the HTTP Status Code of the response:
   • If the status code is not within the 2xx range, the request failed.
   • If the status code is within the 2xx range, proceed to the next step.
2. Check the error field in the JSON response body:
   • If an error field is present, the request encountered an error.
   • If no error field is present, the request was successful.

Here are examples of how HTTP responses may look:

• Success (HTTP status is 2xx and no error field in the response):

  JSON

  {"jsonrpc":"2.0","id":0,"result":"0x127776c"}
  

• Failed (HTTP status is 2xx but the error field is populated):

  JSON

  {"jsonrpc":"2.0","error":{"code":-32002,"message":"Transaction simulation failed"}}
  

Understanding these responses is important for accurately determining the outcome of your requests.

HTTP Status Codes

HTTP Status codes are standardized numeric codes that are returned by our servers in response to a client's HTTP requests. In general, there are 3 categories of HTTP codes that you might encounter when using Alchemy: 2xx , 4xx, and 5xx. HTTP error response can have any combination of JSON-RPC error codes (even for 2xx responses). Below are example HTTP error codes and potential solutions.

🚧

200 HTTP response does not necessarily mean the request was successful.

200 HTTP response indicates that we were able to receive and respond to the request successfully, but there may have been issues actually executing that request on the nodes or on-chain. For example, if you send an eth_call request and the gas is too low, you’d get back a 200 HTTP response but a 3 JSON-RPC error code and an error message indicating execution reverted since gas is too low.

JSON-RPC Error Codes

For JSON-RPC specific errors, you may receive any of the above HTTP Error codes in addition to the JSON RPC error codes specified below.

Error codes range from -32768 to -32000, any code in this range but not defined explicitly is reserved for future use or application-specific errors. For more info on how these are defined check out the JSON-RPC Error specification docs.

Error Messages

Below are a few common error messages and how to solve them.

Common Errors

How to Solve ENOTFOUND getAddrInfo Errors

ENOTFOUND getAddrInfo error is a common issue encountered by developers when trying to make network requests to a specific URL that might not exist any longer.

To resolve this issue, you need to update the URL from eth-mainnet.alchemy.io to eth-mainnet.g.alchemy.com. Open your application where you are making requests to the old URL and replace it with the new one.

Before:

JavaScript

const apiUrl = '<https://eth-mainnet.alchemy.io/v2/YOUR_API_KEY'>;

After:

JavaScript

const apiUrl = '<https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY'>;

Save the changes you made to your application and run it again. The ENOTFOUND getAddrInfo error should no longer occur since you are now using the updated URL. To confirm that the error has been resolved, check your application's output or script, and you should see successful network requests to the new URL without any ENOTFOUND errors.

How to solve ECONNRESET errors?

ECONNRESET errors occur when a TCP connection cannot be established at that time. If you experience ECONNRESET errors, please ensure that your client isn not creating a scenario where new connections are unable to be created. Historically, we have only seen client-side issues causing these errors (if the server were rejecting requests indiscriminately, then it would obviously effect multiple clients simultaneously which has never been the case). If you’re hitting a generic EPROTO error message, it’s possible you’re facing similar issues.

Here are some guidelines to limit client side issues:

1. If you’re using AWS, a NAT gateway can support up to 55,000 simultaneous connections (or approximately 900 connections per second/55,000 connections per minute). Ensure your rate of opening new connections falls within the threshold!
   1. If in AWS, check NAT Gateway for port ErrorPortAllocation errors (guide)
   2. If not in AWS, check to make sure source ports aren’t exhausted
2. For Java, consider implementing a connection pools.
3. For node.js, consider using options.keepAlive to keep the TCP connection alive!
4. Consider enabling HTTP Pipeline (in which you can send more than one request per TCP connection)
5. Ensure systems outside of your production environment are are also not creating too many requests!

If these guidelines don’t help, please request support on our discord or email [email protected].

How we define “successful” vs. “failed” requests in the dashboard

The dashboard includes various charts that indicate the number of successful or failed request across your applications. A few examples of these include:

Daily Request Health Pie on the Homepage

Request Health Chart on the Homepage

Several other pages including apps list, app details, logs, and more.

The definitions used for “success” and “failure” throughout the dashboard are the following:

• Success: HTTP status code is 2xx and the response.error field is empty (null).
• Failure: Any condition that does not meet the success criteria.

These definitions ensure a straightforward approach to interpreting dashboard metrics and aligns with the actual HTTP responses you receive.