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) there are a few places you’ll want to check to see if your request experienced an error:

  1. HTTP Status Codes: Indicate whether or not the request was received and the response was sent back properly. Successful requests are often 2xx HTTP codes, while errors are often 4xx or 5xx.
  2. JSON-RPC Error Codes: Indicate if the request experienced an error when being processed or executed. Successful requests are often 0 JSON-RPC codes, while errors are often -32xxx
  3. Error Messages: While these are not codes, in the case where there was an error, these will indicate what specifically went wrong. Successful requests do not have an error message.

📘

Error Code Combinations

There can be many combinations of HTTP codes and JSON-RPC codes that may indicate an error request. As a rule of thumb, we recommend checking all three of the above identifications to know if something went wrong or not.

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.

CategoryHTTP CodeExample JSON-RPC CodesExample Error MessageMeaningExample Solution
2xx200Any- execution reverted
- err: intrinsic gas too low (supplied gas 50000000)
- filter not found
- already known
Success: the request was received by the client and returned successfully by the server, however, the request may have encountered issues while being processed on chain.Verify that your request is valid.
4xxClient Error: the client had an issue when sending the request
400-32700, -32602, -32600, -32521, -32500- Unsupported method
- Invalid <nth> argument
- Parse error
Bad Request: The request is invalid (e.g incorrect format)Verify your request body and format is correct.
401-32600- Must be authenticated!
- Invalid access key
Unauthorized: You must authenticate your request with an API key. Check out how to create an Alchemy key if you do not have one.Create a new API key
403-32600- Monthly capacity limit exceeded.
- App is inactive.
- Origin not on whitelist.
Forbidden: the server has received the request successfully, but is intentionally refusing to process it due to some missing criteria.- Upgrade tiers to increase capacity
- Create a new API key
- Update allowlist to permit request origin.
429429- Your app has exceeded its compute units per second capacity.Too Many Requests: You've exceeded your concurrent requests capacity or compute units per second capacity. Check out the throughput page for solutions.- Upgrade to increase throughput
- Implement automatic retries
5xxServer Error: there was an error processing the request on the server side.Check out the status page for the latest updates.
500-3200 -32603- Unable to complete request at this time.
- Block <block number> not processed yet. Please try again.
- internal server error
Server error: unable to complete the request due to server issues or due to the block not being processed yet- See the status page for latest updates
- Ensure the requested block is valid, then retry
503-3200Unable to complete request at this time.Server error: unable to complete the request due to server issues- See the status page for latest updates

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.

CodeExample Error MessageMeaning
-32700Parse errorParse error: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600- Must be authenticated!
- Invalid access key
Invalid Request: The JSON sent is not a valid Request object.
-32601Unsupported method: <method>.Method not found: The method does not exist / is not available.
-32602invalid <nth> argument:Invalid params: Invalid method parameter(s).
-32603internal server errorInternal error: Internal JSON-RPC error.
-32000 to -32099Unable to complete request at this time.Server error: Reserved for implementation-defined server-errors.
Anything from
-32099 to -32599 or -32603 to -32699 or -32701 to -32768
- -32500 :AA20 account not deployed, AA25 invalid account nonce
- -32501: COLLECT_LIMIT_EXCEEDED , user operation's call reverted: 0x
Any: Application-defined error or other.
3execution revertedGenerally used for eth_call, eth_estiamteGas, alchemy_getTokenBalances. The data field in the error response will have more details on the root cause.
20 to 63Starknet specific errorsErrors related to Starknet methods. See https://docs.starkware.co/starkex/api/spot/error_codes.htmlfor more details.

Error Messages

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

Error MessageMeaningSolution
already knownThis generally means the transaction already posted and is on the node in a pending state. Sometimes this error occurs when transactions fail at first but are retried when the node already knows of themCheck if you’ve already sent a transaction with the same nonce.
Unspecified origin not on whitelistWhoever is making the request is not on the allowlist for your API key.Safely ignore the request or update your app’s allowlist to include the new request origin
filter not foundFilters expire after 5 minutes of inactivity so if it's not found the filter likely expired.Create a new filter.
Request timed out. Client should retry.Gateway timeouts (usually from nodes).Retry the request.
transaction underpricedTransaction was sent with too low gas.Retry the transaction with higher gas.

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 == 2xx && JSON-RPC== 0 && error_message == null
  • Failure: !success

In other words, successful requests are when the HTTP code is a 2xx and the JSON-RPC code is 0 and there is no error message. All other cases are marked as failed requests.

ReadMe