Error Reference

Learn about the standard JSON-RPC error codes and Alchemy's custom error codes.

HTTP Status Codes

In addition to the standard Ethereum JSON-RPC error codes, Alchemy will return the following status codes for HTTP requests:

HTTP Status Codes

CodeMeaning
400Bad Request -- Your request is invalid. Double-check your JSON-RPC body.
401Unauthorized -- You must authenticate your request with an API key. Check out how to Alchemy Quickstart Guide if you do not have one.
403Forbidden -- You've hit your capacity limit, or your request was rejected by your app's whitelist settings.
429Too Many Requests -- You've exceeded your concurrent requests capacity or Compute Units per second capacity. Check out the Throughput page for solutions.
500Internal Server Error -- We're unable to process your request right now. Get in touch with us if you see this.

Example Response

// Example 429 Error
{
    "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 https://docs.alchemy.com/guides/rate-limits"
    },
    "id": 1
}

Standard JSON-RPC Errors

For JSON-RPC specific errors, Alchemy returns a 200 with the JSON-RPC error in the JSON response.

JSON-RPC Error Codes

CodePossible Return MessageDescription
429Your app has exceeded its compute unit per second capacity.Check out the Throughput page for solutions.
-32000Server errorReserved for implementation-defined server-errors. See hint below.
-32001 to -32099Parity errorsThese errors are parity specific and thus relevant for when using the Kovan network, see the parity sectionbelow.
-32600Invalid RequestThe JSON sent is not a valid Request object.
-32601Method not foundThe method does not exist / is not available.
-32602Invalid parameterInvalid method parameter(s).
-32603Internal errorInternal JSON-RPC error.
-32700Parse errorInvalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

📘

NOTE:

-32000 is used for many server errors. Here are a few common examples:

"already known"

  • This 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 them

"Unspecified origin not on whitelist"

  • This error means whoever is making the request is not on the whitelist for using your API key.

"filter not found"

  • Filters expire after 5 minutes of inactivity so if it's not found the filter likely expired.

"Request timed out. Client should retry."

  • Gateway timeouts (usually from nodes). Clients should retry the request.

"transaction underpriced"

  • Transaction was sent with too low gas. Re-send the transaction with higher gas!

Example Response

{
    "jsonrpc":"2.0",
    "error":{
        "code":-32602,
        "message": "Invalid params: invalid length 63, expected a 0x-prefixed, padded, hex-encoded hash with length 64."
    },
    "id":1
}

Error Messages

  • out of gas: not enough gas for the transaction or call, contact us at support

Kovan Error Codes

These errors should occur when using the Kovan network.

CodeMessage
-32000UNSUPPORTED_REQUEST
-32001NO_WORK
-32002NO_AUTHOR
-32003NO_NEW_WORK
-32004NO_WORK_REQUIRED
-32009UNKNOWN_ERROR
-32010TRANSACTION_ERROR
-32015EXECUTION_ERROR
-32016EXCEPTION_ERROR
-32017DATABASE_ERROR
-32020ACCOUNT_LOCKED
-32021PASSWORD_INVALID
-32023ACCOUNT_ERROR
-32040REQUEST_REJECTED
-32041REQUEST_REJECTED_LIMIT
-32042REQUEST_NOT_FOUND
-32055ENCRYPTION_ERROR
-32058ENCODING_ERROR
-32060FETCH_ERROR
-32065NO_LIGHT_PEERS
-32070DEPRECATED

Custom Error Codes

CodePossible Return MessageDescription
1UnauthorizedShould be used when some action is not authorized, e.g. sending from a locked account.
2Action not allowedShould be used when some action is not allowed, e.g. preventing an action, while another depending action is processing on, like sending again when a confirmation popup is shown to the user.
3Execution errorWill contain a subset of custom errors in the data field. See below.

Custom Error Fields

Custom error 3 can contain custom error(s) to further explain what went wrong.
They will be contained in the data field of the RPC error message as follows:

📘

NOTE:

Custom Error Fields are defined at the contract level. Therefore, the types within the error field might vary by contract. Read more about this here.

{
    code: 3,
    message: 'Execution error',
    data: [{
        code: 102,
        message: 'Innsufficient gas'
    },
    {
        code: 103,
        message: 'Gas limit exceeded'
    }]
}
CodePossible Return MessageDescription
100X doesn't existShould be used when something which should be there is not found. (Doesn’t apply to eth_getTransactionBy_ and eth_getBlock_. They return a success with value null)
101Requires etherShould be used for actions which require something else (gas or value)
102Gas too lowShould be used when the value of gas given is too low
103Gas limit exceededShould be used when a limit is exceeded (for the gas limit in a block)
104RejectedShould be used when an action was rejected, e.g. because of its content (too long contract code, contains wrong characters, etc.)
105Ether too lowShould be used when the value of Ether given is too low

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:

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

After:

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].