Error Reference
Learn about the standard JSON-RPC error codes and Alchemy’s custom error codes.
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:
-
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.
- If the status code is not within the
-
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.
- If an
Here are examples of how HTTP responses may look:
-
Success (HTTP status is
2xx
and no error field in the response):json -
Failed (HTTP status is
2xx
but the error field is populated):json
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 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:
-
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!
- If in AWS, check NAT Gateway for port ErrorPortAllocation errors (guide)
- If not in AWS, check to make sure source ports aren’t exhausted
-
For Java, consider implementing a connection pools.
-
For node.js, consider using options.keepAlive to keep the TCP connection alive!
-
Consider enabling HTTP Pipeline (in which you can send more than one request per TCP connection)
-
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 theresponse.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.